feat(model,capacity,vision,io): per-persona 路由 + 本地三级(默认关) + L3 分类 + OCR 独立模型 + image-crop 工具（裁决 03.4.1/03.4.3/14.4.1/14.4.4/14.4.5）

- 03.4.1：per-persona 路由载体选 models.json（组内新增 personaModels/personaProviders + 校验 + PersonaRoute()）， Router/RuntimeLLM 快照绑定、loop 流式路径按该 turn 的 persona 路由；主步用路由结果、降级步钉自己的模型 - 03.4.3：本地第三级降级链（LLM_LOCAL_*，Configured() 含 Enabled ⇒ **默认关**），warn 标注来源 - 14.4.4：capacity 接入 L3（分类器接口 + TTL 缓存 + 严格 JSON 解析），CAPACITY_L3_ENABLED **默认 false** - 14.4.1：语义修正 —— group.multimodal 才是「主模型能否收图」（env 路径不再臆断），LLM_VISION_MODEL 只配视觉工具； vision/OCR 可各用不同模型；runtime 不再因有图抢路由（vision.Router 是唯一分层权威） - 14.4.5：新增 image-crop 工具（工具数 5→6，策略默认 owner-only），schema 支持按区域裁切 - 组合根：wire_runtime 读 group.Multimodal；capacity 装配拆出 wire_capacity.go（守 500 行） - 复核：`go build`/`go vet`/各包 `go test -count=1` 全绿；**6 条变异反证**先红后还原（含作者自查出的 2 条假阳性变异） - 未落：按 provider 的 thinking 开关（需 openai_encode.go/openai.go 文件面）、persona awakening（需 loader 文件面）
2026-10-04 12:44:52 +08:00
1 parent 63e5b70e3d
commit fa33c79e11
@@ -88,10 +88,23 @@ type LLMConfig struct {
 	Model    string `env:"LLM_MODEL"`
 	Fallback string `env:"LLM_FALLBACK_MODEL"`

-	// VisionModel is the dedicated model used for image/vision requests. When
-	// set, the model router routes image content to it (see model.Router.WithVisionModel).
+	// VisionModel is the dedicated model behind the vision tool (image
+	// understanding). It is the tool's model, not the main model's ability: the
+	// per-persona/per-request routing decision belongs to the vision Router, and
+	// the main model's own image input capability is declared by the active
+	// models.json group's multimodal flag (裁决 14.4.1/14.4.5)。
 	VisionModel string `env:"LLM_VISION_MODEL"`

+	// OCRModel is the dedicated model behind the OCR tool. Empty reuses
+	// VisionModel, so OCR keeps working without a second endpoint (裁决 14.4.1
+	// 的「独立视觉模型 + OCR 模型」)。
+	OCRModel string `env:"LLM_OCR_MODEL"`
+
+	// Local is the optional third degradation level (裁决 03.4.3): primary →
+	// fallback → local. It defaults to off because the current machine cannot run
+	// a local model comfortably; when off the chain keeps its two-level shape.
+	Local LocalLLMConfig
+
 	// FallbackMaxTokens caps the last-resort fallback model in a group's chain
 	// (primary → fallback). It is the final safety budget: it only applies when
 	// the chain actually has a fallback step, that group sets no per-group
@@ -107,6 +120,33 @@ type LLMConfig struct {
 	AnthropicFallback string `env:"ANTHROPIC_FALLBACK_MODEL"`
 }

+// LocalLLMConfig configures the optional local model rung — the third level of
+// the primary → fallback → local degradation chain (裁决 03.4.3). It is opt-in
+// and defaults to off: a machine that cannot run a local model comfortably must
+// not silently pay for one. It becomes an active chain step only when Enabled is
+// true and both BaseURL and Model are set; anything less is reported and skipped
+// rather than producing a half-configured step.
+type LocalLLMConfig struct {
+	// Enabled turns the local rung on. Default false (project red line: 本地模型可开关，默认关).
+	Enabled bool `env:"LLM_LOCAL_ENABLED" default:"false"`
+	// Provider is the local endpoint's wire protocol: "openai" (llama.cpp /
+	// ollama / vLLM compatible endpoints) or "anthropic". Empty means openai.
+	Provider string `env:"LLM_LOCAL_PROVIDER" default:"openai"`
+	// BaseURL is the local endpoint's base URL (e.g. http://127.0.0.1:8080/v1).
+	BaseURL string `env:"LLM_LOCAL_BASE_URL"`
+	// APIKey is the local endpoint's key; empty is normal for a local server.
+	APIKey string `env:"LLM_LOCAL_API_KEY"`
+	// Model is the local model name. Without it the rung stays off.
+	Model string `env:"LLM_LOCAL_MODEL"`
+}
+
+// Configured reports whether the local rung has enough configuration to act as a
+// chain step. Enabled alone is not enough: a missing endpoint or model must not
+// become a step that can only fail.
+func (l LocalLLMConfig) Configured() bool {
+	return l.Enabled && strings.TrimSpace(l.BaseURL) != "" && strings.TrimSpace(l.Model) != ""
+}
+
 // EmbeddingConfig holds the optional semantic embedding API settings. When
 // unset, the runtime falls back to built-in n-gram/FTS vectors.
 type EmbeddingConfig struct {
@@ -246,6 +286,15 @@ type CapacityConfig struct {
 	// reflection-based loader only supports scalars and []string), matching the
 	// MCP config pattern.
 	ToolSetsJSON string `env:"CAPACITY_TOOL_SETS"`
+	// L3Enabled turns on the model-assisted intent layer (design/14 §2.2 L3;
+	// 裁决 14.4.4, keys chosen as the landing suggestion the owner authorized).
+	// It costs one extra model call for an undecided turn, so it defaults to off:
+	// off means the layer never runs and L1/L2/L4 behave exactly as before.
+	L3Enabled bool `env:"CAPACITY_L3_ENABLED" default:"false"`
+	// L3CacheTTL is how long a model-assisted classification of the same turn text
+	// is reused (a Go duration string such as "5m"). Zero or unparsable disables
+	// reuse; empty selects the code default of 5m.
+	L3CacheTTL string `env:"CAPACITY_L3_CACHE_TTL" default:"5m"`
 }

 // MCPServer describes a single MCP server: a stdio subprocess (Command/Args) or
@@ -47,6 +47,18 @@ type Group struct {
 	// last-resort fallback step then falls back to LLM_FALLBACK_MAX_TOKENS, and
 	// beyond that the adapter default applies.
 	MaxTokens int `json:"maxTokens,omitempty"`
+	// PersonaModels binds an individual persona to its own model name within this
+	// group (裁决 03.4.1: the "role" of per-role routing is the persona a turn
+	// answers as, not the LLM message role). The carrier is deliberately
+	// models.json rather than configs/personas/*.yaml, so the panel can edit the
+	// binding together with the rest of the provider configuration and no persona
+	// schema change is needed. An unknown persona id falls back to the group's
+	// default model, so a removed persona never breaks routing.
+	PersonaModels map[string]string `json:"personaModels,omitempty"`
+	// PersonaProviders binds an individual persona to another vendor's protocol
+	// (裁决 03.4.1 的 per-persona provider). Pair it with PersonaModels; an entry
+	// without a provider keeps this group's protocol.
+	PersonaProviders map[string]string `json:"personaProviders,omitempty"`
 }

 // ErrInvalidGroup is returned when a group fails schema validation.
@@ -75,9 +87,49 @@ func (g Group) Validate() error {
 	if g.MaxTokens < 0 {
 		return fmt.Errorf("maxTokens must be >= 0, got %d", g.MaxTokens)
 	}
+	if err := validatePersonaMap("personaModels", g.PersonaModels, false); err != nil {
+		return err
+	}
+	if err := validatePersonaMap("personaProviders", g.PersonaProviders, true); err != nil {
+		return err
+	}
 	return nil
 }

+// validatePersonaMap checks a persona-keyed binding map: every key must be a
+// non-empty persona id and every value a non-empty value. When providers is true
+// the values must additionally be a known protocol, so a typo in a per-persona
+// provider fails the group loudly instead of silently routing to the default.
+func validatePersonaMap(field string, m map[string]string, providers bool) error {
+	for persona, value := range m {
+		if strings.TrimSpace(persona) == "" {
+			return fmt.Errorf("%s: persona id must not be empty", field)
+		}
+		if strings.TrimSpace(value) == "" {
+			return fmt.Errorf("%s: value for persona %q must not be empty", field, persona)
+		}
+		if providers && value != ProviderOpenAI && value != ProviderAnthropic {
+			return fmt.Errorf("%s: provider %q for persona %q must be openai or anthropic", field, value, persona)
+		}
+	}
+	return nil
+}
+
+// PersonaRoute returns the per-persona model/provider binding, if one is
+// configured for persona. An empty model (or an unknown persona) is reported as
+// ok=false so the caller keeps the group's default binding.
+func (g Group) PersonaRoute(persona string) (model, provider string, ok bool) {
+	persona = strings.TrimSpace(persona)
+	if persona == "" {
+		return "", "", false
+	}
+	model = strings.TrimSpace(g.PersonaModels[persona])
+	if model == "" {
+		return "", "", false
+	}
+	return model, strings.TrimSpace(g.PersonaProviders[persona]), true
+}
+
 // ToLLMConfig maps a group to the flat LLMConfig consumed by the adapter
 // factory. The group's provider selects which config block is populated.
 func (g Group) ToLLMConfig() config.LLMConfig {
@@ -161,26 +213,32 @@ func loadFile(path string) ([]Group, error) {
 // GroupFromEnv synthesizes a single group from the active env LLM block: the
 // anthropic block when LLM_PROVIDER=anthropic, otherwise the flat OpenAI-compatible
 // block. It is the .env fallback used when models.json is absent or invalid.
+//
+// Multimodal stays false here: the flat env block has no way to declare whether
+// the main model accepts image input, and claiming a capability the endpoint may
+// not have is worse than routing the image through the vision/OCR tool (which is
+// exactly what the tool exists for). The declaration lives on the models.json
+// group's `multimodal` flag, which the provider panel writes (design/06 §0 首条;
+// 裁决 14.4.1). LLM_VISION_MODEL configures the vision *tool's* model, not the
+// main model's ability.
 func GroupFromEnv(env config.LLMConfig) []Group {
 	if env.Provider == ProviderAnthropic {
 		return []Group{{
-			ID:         ProviderAnthropic,
-			Provider:   ProviderAnthropic,
-			BaseURL:    env.AnthropicBaseURL,
-			APIKey:     env.AnthropicAPIKey,
-			Model:      env.AnthropicModel,
-			Fallback:   env.AnthropicFallback,
-			Multimodal: env.VisionModel != "",
+			ID:       ProviderAnthropic,
+			Provider: ProviderAnthropic,
+			BaseURL:  env.AnthropicBaseURL,
+			APIKey:   env.AnthropicAPIKey,
+			Model:    env.AnthropicModel,
+			Fallback: env.AnthropicFallback,
 		}}
 	}
 	return []Group{{
-		ID:         ProviderOpenAI,
-		Provider:   ProviderOpenAI,
-		BaseURL:    env.BaseURL,
-		APIKey:     env.APIKey,
-		Model:      env.Model,
-		Fallback:   env.Fallback,
-		Multimodal: env.VisionModel != "",
+		ID:       ProviderOpenAI,
+		Provider: ProviderOpenAI,
+		BaseURL:  env.BaseURL,
+		APIKey:   env.APIKey,
+		Model:    env.Model,
+		Fallback: env.Fallback,
 	}}
 }