refactor: consolidate smart routing into model specs (#75)

schemas/model-spec.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://desirecore.net/schemas/config-center/model-spec.schema.json",
   "title": "ModelSpecFile",
-  "description": "模型规格库（compute/model-specs/*.json）数据契约。\n\n用途：维护模型的「内在参数」（上下文窗口、最大输出、能力标签、serviceType、默认采样参数等），这些参数与「从哪家 provider、什么价格调用」无关，是模型的客观物理属性。\n\n接入路径（首期仅 cloud）：登录后从 NewAPI pricing 拉到的模型，只承担「可用模型清单 + 价签」职责；客户端按 modelName 用通用匹配机制查询本规格库，补全 tags 无法表达的结构化参数（maxOutputTokens / defaultTemperature 等）。\n\n与 provider.schema.json 的区别：provider 文件是「完整 provider 接入定义」，本文件是「跨 provider 共享的模型参数字典」。本文件是老客户端不会读取的新文件，因此 schema 可以更宽松（允许 null），且不破坏已发布客户端兼容契约。\n\n严禁写入价格字段（inputPrice/outputPrice/cache 等）——价签真相源永远是 NewAPI pricing。",
+  "description": "模型规格库（compute/model-specs/*.json）数据契约。\n\n用途：维护模型的唯一规格主数据：内在参数（上下文窗口、最大输出、能力标签、serviceType、默认采样参数等）以及智能路由策略（量级、排序、Agent 可选性和标准化 reasoning 合同）。同一事实不得再写入独立 smart-routing 目录。\n\nProvider 文件只描述接入面、可用性和明确的接入面覆盖；历史 Provider 条目中已有的规格字段为旧客户端兼容副本，不能覆盖本文件。\n\n严禁写入价格字段（inputPrice/outputPrice/cache 等）——价签真相源永远是 NewAPI pricing。",
   "type": "object",
   "required": ["specs"],
   "properties": {
@@ -52,6 +52,66 @@
           },
           "additionalProperties": false
         },
+        "routing": {
+          "type": "object",
+          "description": "智能路由策略。存在即表示该精确模型可进入路由候选；模型能力和 reasoning 合同均以本条目为准，Provider 只能为接入面收紧。",
+          "required": ["tier", "routingPriority", "eligibleForAgent", "defaultReference", "reasoning"],
+          "properties": {
+            "tier": {
+              "type": "string",
+              "enum": ["flagship", "balanced", "lightweight"],
+              "description": "模型在智能路由中的能力量级。"
+            },
+            "routingPriority": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 10000,
+              "description": "同一量级内的稳定优先级，数值越小越优先。"
+            },
+            "eligibleForAgent": {
+              "type": "boolean",
+              "description": "是否允许作为 Agent 主模型；媒体专用模型必须为 false。"
+            },
+            "defaultReference": {
+              "type": "boolean",
+              "description": "是否是默认模型的策略参考，只影响同级排序，不是强制选择。"
+            },
+            "reasoning": {
+              "type": "object",
+              "description": "模型级标准化 reasoning 合同。auto 为不发送参数，off 为显式关闭；Provider 接入面可收紧此集合，但不得扩张。",
+              "required": ["supportedModes", "defaultMode"],
+              "properties": {
+                "supportedModes": {
+                  "type": "array",
+                  "minItems": 1,
+                  "uniqueItems": true,
+                  "items": {
+                    "type": "string",
+                    "enum": ["auto", "off", "minimal", "low", "medium", "high", "xhigh", "max"]
+                  },
+                  "description": "产品层可用的 reasoning 档位。"
+                },
+                "defaultMode": {
+                  "type": "string",
+                  "enum": ["auto", "off", "minimal", "low", "medium", "high", "xhigh", "max"],
+                  "description": "没有显式请求时的策略默认档位，必须包含在 supportedModes 中。"
+                }
+              },
+              "allOf": [
+                { "if": { "properties": { "defaultMode": { "const": "auto" } } }, "then": { "properties": { "supportedModes": { "contains": { "const": "auto" } } } } },
+                { "if": { "properties": { "defaultMode": { "const": "off" } } }, "then": { "properties": { "supportedModes": { "contains": { "const": "off" } } } } },
+                { "if": { "properties": { "defaultMode": { "const": "minimal" } } }, "then": { "properties": { "supportedModes": { "contains": { "const": "minimal" } } } } },
+                { "if": { "properties": { "defaultMode": { "const": "low" } } }, "then": { "properties": { "supportedModes": { "contains": { "const": "low" } } } } },
+                { "if": { "properties": { "defaultMode": { "const": "medium" } } }, "then": { "properties": { "supportedModes": { "contains": { "const": "medium" } } } } },
+                { "if": { "properties": { "defaultMode": { "const": "high" } } }, "then": { "properties": { "supportedModes": { "contains": { "const": "high" } } } } },
+                { "if": { "properties": { "defaultMode": { "const": "xhigh" } } }, "then": { "properties": { "supportedModes": { "contains": { "const": "xhigh" } } } } },
+                { "if": { "properties": { "defaultMode": { "const": "max" } } }, "then": { "properties": { "supportedModes": { "contains": { "const": "max" } } } } }
+              ],
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false
+        },
         "spec": {
           "type": "object",
           "description": "模型内在参数（不含任何价格字段）",

schemas/model-specs-index.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://desirecore.net/schemas/config-center/model-specs-index.schema.json",
+  "title": "ModelSpecsIndex",
+  "description": "compute/model-specs 的加载顺序与智能路由三档定义。量级属于 model-specs 域，不得另建 smart-routing 目录。",
+  "type": "object",
+  "required": ["order", "routingTiers"],
+  "properties": {
+    "description": {
+      "type": "string",
+      "description": "索引说明。"
+    },
+    "order": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 },
+      "description": "模型规格文件 basename 的稳定加载顺序。"
+    },
+    "routingTiers": {
+      "type": "array",
+      "minItems": 3,
+      "maxItems": 3,
+      "items": {
+        "type": "object",
+        "required": ["id", "label", "labelEn", "description", "fallbackOrder"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "enum": ["flagship", "balanced", "lightweight"],
+            "description": "量级稳定标识。"
+          },
+          "label": { "type": "string", "minLength": 1, "description": "中文标签。" },
+          "labelEn": { "type": "string", "minLength": 1, "description": "英文标签。" },
+          "description": { "type": "string", "minLength": 1, "description": "适用任务说明。" },
+          "fallbackOrder": {
+            "type": "array",
+            "minItems": 3,
+            "maxItems": 3,
+            "uniqueItems": true,
+            "items": { "type": "string", "enum": ["flagship", "balanced", "lightweight"] },
+            "description": "该档位缺少可用候选时的量级降级/升级顺序，首项必须等于 id。"
+          }
+        },
+        "additionalProperties": false
+      },
+      "description": "智能路由量级定义与回退策略。"
+    }
+  },
+  "additionalProperties": false
+}

schemas/provider.schema.json

@@ -174,7 +174,7 @@
     },
     "models": {
       "type": "array",
-      "description": "此提供商下的可用模型列表",
+      "description": "此接入面当前可调用的模型列表。可用性、凭据、价格与 API 映射属于 Provider；模型能力、上下文、Smart tier 与产品 reasoning 合同以 compute/model-specs 为准。",
       "items": { "$ref": "#/definitions/model" }
     },
     "tombstones": {
@@ -196,18 +196,18 @@
       "properties": {
         "modelName": {
           "type": "string",
-          "description": "模型 ID，用于 API 调用（如 gpt-5-mini、claude-sonnet-4）",
+          "description": "此 Provider 接入面实际接受的模型 ID，用于 API 调用并与 ModelSpec 的精确/受控别名匹配（如 gpt-5-mini、claude-sonnet-4）。",
           "minLength": 1
         },
         "displayName": {
           "type": "string",
-          "description": "模型显示名称（如 GPT-5 Mini、Claude Sonnet 4）",
+          "description": "旧客户端展示兼容副本。新 Smart 路径以 ModelSpec.displayName 为模型事实，此字段仅随接入面保留。",
           "minLength": 1
         },
         "serviceType": {
           "type": ["string", "array"],
           "items": { "type": "string" },
-          "description": "服务类型，支持单个字符串或数组：chat、reasoning、fast、responses、translation、tts、asr、voice_clone、realtime_voice、simultaneous_interpret、vision、ocr、image_gen、video_gen、embedding、rerank、omni、computer_use 等"
+          "description": "旧客户端兼容的接入面服务声明；新 Smart 路径以 ModelSpec.spec 为能力事实。支持单个字符串或数组：chat、reasoning、fast、responses、translation、tts、asr、voice_clone、realtime_voice、simultaneous_interpret、vision、ocr、image_gen、video_gen、embedding、rerank、omni、computer_use 等"
         },
         "description": {
           "type": "string",
@@ -215,17 +215,17 @@
         },
         "contextWindow": {
           "type": "number",
-          "description": "上下文窗口大小（token 数）",
+          "description": "旧客户端兼容副本；Smart 以 ModelSpec.spec.contextWindow 为模型事实，本地接入面覆盖只能收紧。",
           "minimum": 0
         },
         "maxOutputTokens": {
           "type": "number",
-          "description": "单次请求最大输出 token 数",
+          "description": "旧客户端兼容副本；新模型规格以 ModelSpec.spec.maxOutputTokens 为准。",
           "minimum": 0
         },
         "capabilities": {
           "type": "array",
-          "description": "模型能力标签：chat、vision、tool_use、code、reasoning 等",
+          "description": "旧客户端兼容副本；Smart 的能力标签以 ModelSpec.spec.capabilities 为准，接入面或用户覆盖只能收紧，不能扩张。",
           "items": { "type": "string" }
         },
         "inputPrice": {
@@ -252,7 +252,7 @@
         },
         "extra": {
           "type": "object",
-          "description": "模型特定配置：如 TTS 模型音色列表、ASR 支持格式、模型级 reasoning effort 能力等。这里是兼容扩展面：旧客户端会安全保留并忽略未知子字段。",
+          "description": "接入面特定配置：如 TTS 模型音色列表、ASR 支持格式与本 Provider 实际接受的 reasoning effort。这里是兼容扩展面：旧客户端会安全保留并忽略未知子字段。",
           "properties": {
             "reasoning": {
               "type": "object",
@@ -266,12 +266,12 @@
                     "type": "string",
                     "enum": ["none", "minimal", "low", "medium", "high", "xhigh", "max"]
                   },
-                  "description": "当前模型与接入面实际接受的 OpenAI reasoning effort。none 在产品层映射为 off；Ultra 是多 Agent 编排模式，禁止写入。"
+                  "description": "当前接入面实际接受的 OpenAI reasoning effort；它只能收紧精确 ModelSpec.routing.reasoning 合同，不能扩张。none 在产品层映射为 off；Ultra 是多 Agent 编排模式，禁止写入。"
                 },
                 "defaultEffort": {
                   "type": "string",
                   "enum": ["minimal", "low", "medium", "high", "xhigh", "max"],
-                  "description": "当前模型在此接入面的推荐显式默认档位，必须同时存在于 supportedEfforts。"
+                  "description": "当前接入面推荐的显式默认档位；仅当它仍属于 ModelSpec 合同时生效，且必须同时存在于 supportedEfforts。"
                 }
               },
               "allOf": [

schemas/smart-model-catalog.schema.json

@@ -1,273 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://desirecore.net/schemas/smart-model-catalog.json",
-  "title": "SmartModelCatalog",
-  "description": "智能路由量级、Provider 和模型能力目录；Config Center、内置兜底与未来接口共用此契约。",
-  "type": "object",
-  "required": [
-    "version",
-    "updatedAt",
-    "source",
-    "tiers",
-    "providers"
-  ],
-  "properties": {
-    "$schema": {
-      "type": "string",
-      "description": "本数据对应的 JSON Schema 标识。"
-    },
-    "version": {
-      "type": "integer",
-      "minimum": 1,
-      "maximum": 1,
-      "description": "目录结构版本；当前客户端只接受 v1，不兼容的新语义必须递增版本并由新客户端接入。"
-    },
-    "updatedAt": {
-      "type": "string",
-      "format": "date-time",
-      "description": "本目录最近一次人工/自动核对时间。"
-    },
-    "source": {
-      "type": "string",
-      "enum": [
-        "builtin",
-        "config-center",
-        "provider-api"
-      ],
-      "description": "目录来源：config-center=配置中心下发，builtin=客户端离线兜底，provider-api=未来接口实时数据。"
-    },
-    "tiers": {
-      "type": "array",
-      "minItems": 3,
-      "maxItems": 3,
-      "items": {
-        "type": "object",
-        "required": [
-          "id",
-          "label",
-          "labelEn",
-          "description",
-          "defaultReasoning"
-        ],
-        "properties": {
-          "id": {
-            "type": "string",
-            "enum": [
-              "flagship",
-              "balanced",
-              "lightweight"
-            ],
-            "description": "智能路由量级：flagship=最高能力，balanced=质量与成本平衡，lightweight=最快最省。"
-          },
-          "label": {
-            "type": "string",
-            "minLength": 1,
-            "description": "中文量级标签。"
-          },
-          "labelEn": {
-            "type": "string",
-            "minLength": 1,
-            "description": "英文量级标签。"
-          },
-          "description": {
-            "type": "string",
-            "minLength": 1,
-            "description": "该量级的任务选择目标。"
-          },
-          "defaultReasoning": {
-            "type": "string",
-            "enum": [
-              "auto",
-              "off",
-              "minimal",
-              "low",
-              "medium",
-              "high",
-              "xhigh",
-              "max"
-            ],
-            "description": "该量级在模型支持时优先采用的默认思考深度。"
-          }
-        },
-        "additionalProperties": false
-      },
-      "description": "三档量级的自描述定义。"
-    },
-    "providers": {
-      "type": "array",
-      "minItems": 1,
-      "items": {
-        "type": "object",
-        "required": [
-          "providerId",
-          "provider",
-          "displayName",
-          "models"
-        ],
-        "properties": {
-          "providerId": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 200,
-            "description": "compute.json 中的 Provider 唯一 ID。"
-          },
-          "provider": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 120,
-            "description": "Provider 协议标识。"
-          },
-          "displayName": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 200,
-            "description": "Provider 展示名称。"
-          },
-          "models": {
-            "type": "array",
-            "minItems": 1,
-            "items": {
-              "type": "object",
-              "required": [
-                "model",
-                "displayName",
-                "tier",
-                "routingPriority",
-                "serviceTypes",
-                "capabilities",
-                "contextWindow",
-                "maxOutputTokens",
-                "supportedReasoning",
-                "defaultReasoning",
-                "eligibleForAgent",
-                "defaultReference"
-              ],
-              "properties": {
-                "model": {
-                  "type": "string",
-                  "minLength": 1,
-                  "maxLength": 300,
-                  "description": "传给对应 Provider 的真实 modelName；禁止使用 smart 等虚拟名称。"
-                },
-                "displayName": {
-                  "type": "string",
-                  "minLength": 1,
-                  "maxLength": 200,
-                  "description": "客户端展示名称。"
-                },
-                "tier": {
-                  "type": "string",
-                  "enum": [
-                    "flagship",
-                    "balanced",
-                    "lightweight"
-                  ],
-                  "description": "此模型在智能路由中的能力量级。"
-                },
-                "routingPriority": {
-                  "type": "integer",
-                  "minimum": 0,
-                  "maximum": 10000,
-                  "description": "同一量级内的稳定选择顺序，数值越小越优先；凭据与硬能力校验仍先于此排序。"
-                },
-                "serviceTypes": {
-                  "type": "array",
-                  "minItems": 1,
-                  "maxItems": 16,
-                  "uniqueItems": true,
-                  "items": {
-                    "type": "string",
-                    "minLength": 1,
-                    "maxLength": 64,
-                    "pattern": "^[a-z0-9_]+$",
-                    "description": "可用于任务硬约束匹配的规范能力标签，例如 vision、code、tool_use、long_context。"
-                  },
-                  "description": "模型服务类型快照，例如 chat、reasoning、image_gen、video_gen。"
-                },
-                "capabilities": {
-                  "type": "array",
-                  "maxItems": 64,
-                  "uniqueItems": true,
-                  "items": {
-                    "type": "string",
-                    "minLength": 1,
-                    "maxLength": 64,
-                    "pattern": "^[a-z0-9_]+$",
-                    "description": "可用于任务硬约束匹配的规范能力标签，例如 vision、code、tool_use、long_context。"
-                  },
-                  "description": "模型能力快照；任务 requiredCapabilities 必须全部命中。"
-                },
-                "contextWindow": {
-                  "type": [
-                    "integer",
-                    "null"
-                  ],
-                  "minimum": 1,
-                  "maximum": 10000000,
-                  "description": "上下文窗口 token 数；非文本模型或未知时为 null。"
-                },
-                "maxOutputTokens": {
-                  "type": [
-                    "integer",
-                    "null"
-                  ],
-                  "minimum": 1,
-                  "maximum": 1000000,
-                  "description": "最大输出 token 数；未知或不适用时为 null。"
-                },
-                "supportedReasoning": {
-                  "type": "array",
-                  "minItems": 1,
-                  "maxItems": 8,
-                  "uniqueItems": true,
-                  "items": {
-                    "type": "string",
-                    "enum": [
-                      "auto",
-                      "off",
-                      "minimal",
-                      "low",
-                      "medium",
-                      "high",
-                      "xhigh",
-                      "max"
-                    ],
-                    "description": "本次 Run 或当前 assignment 的思考深度；最终值仍受目标 Provider × Model 能力矩阵约束。"
-                  },
-                  "description": "该 Provider × Model 接入面声明的可用 reasoning 档位。"
-                },
-                "defaultReasoning": {
-                  "type": "string",
-                  "enum": [
-                    "auto",
-                    "off",
-                    "minimal",
-                    "low",
-                    "medium",
-                    "high",
-                    "xhigh",
-                    "max"
-                  ],
-                  "description": "未显式指定时的模型参考 reasoning；路由还会结合量级默认值并做能力协商。"
-                },
-                "eligibleForAgent": {
-                  "type": "boolean",
-                  "description": "是否可作为 Agent 主模型。图像/视频生成、ASR/TTS 等专用模型为 false。"
-                },
-                "defaultReference": {
-                  "type": "boolean",
-                  "description": "是否为 Provider/defaultServiceMap 给出的默认参考。它只影响同级排序，不是强制答案。"
-                }
-              },
-              "additionalProperties": false
-            },
-            "description": "该接入面当前已核对的模型目录。"
-          }
-        },
-        "additionalProperties": false
-      },
-      "description": "参与智能路由和能力匹配的 Provider 目录。"
-    }
-  },
-  "additionalProperties": false
-}