feat(model): capability-driven model management and unified provider invocation layer

.env.example

@@ -183,6 +183,12 @@ REDIS_PREFIX=stream:
 # 后台任务每模型并发上限（0/负数禁用；交互 chat 不受其限制）
 # WEKNORA_MODEL_MAX_CONCURRENCY=32
 
+# 模型参数目录来源：GITHUB / CNB / LOCAL（默认 LOCAL，使用内置 models.json 离线兜底；
+# 镜像地址确定后切 GITHUB/CNB，非法值告警并回落 LOCAL）
+# WEKNORA_MODELS_CATALOG=LOCAL
+# 远端模型列表探测超时秒数（POST /models/remote-catalog，默认 8）
+# WEKNORA_REMOTE_CATALOG_TIMEOUT_SECONDS=8
+
 # ========== B3. 文件存储（通用）==========
 # 文件存储类型：local / minio / cos / tos / s3 / obs / oss / dummy。
 STORAGE_TYPE=local

.gitignore

@@ -63,3 +63,13 @@ miniprogram/project.private.config.json
 
 # Locally built BrowserSkill runtime and extension bundles
 /artifacts/browserskill/
+
+# 模型管理设计文档（本地评审用，不入库/不随 PR 提交，2026-09-15 裁定）
+/CONTEXT.md
+/docs/adr/0001-saved-model-config-never-auto-refreshed.md
+/docs/adr/0002-model-level-thinking-levels-catalog-or-user-pick.md
+/docs/adr/0003-scope-model-management-plus-unified-invocation.md
+/docs/adr/0004-model-types-converge-to-four-facets-vision-rides-modalities.md
+
+# fork 本地的手动 docker 构建流水线（不入上游，2026-09-15）
+/.github/workflows/docker-build.yaml

.golangci.yml

@@ -4,10 +4,18 @@ linters:
     - lll           # 控制行宽
     - govet
     - revive
+    - exhaustive    # 仅检查标注 //exhaustive:enforce 的 switch（如适配器 role 映射）
   settings:
     lll:
       line-length: 120
       tab-width: 4
+    exhaustive:
+      explicit-exhaustive-switch: true
+    errcheck:
+      exclude-functions:
+        # gin.Context.Error returns the error for chaining; repo-wide the return is
+        # deliberately ignored (64 pre-existing bare calls).
+        - (*github.com/gin-gonic/gin.Context).Error
   exclusions:
     paths:
       # swag embeds OpenAPI as single-line JSON strings; line-length is not meaningful.

cli/cmd/model/create.go

@@ -32,7 +32,7 @@ var createSourceValues = []string{string(sdk.ModelSourceLocal), string(sdk.Model
 // canonicalModelType maps the server's frontend term "chat" to the KnowledgeQA
 // enum — that is the server's own /models/providers vocabulary (see its
 // frontendToModelType map). The other frontend terms (embedding / rerank /
-// vllm / asr) already match the enum case-insensitively, so no alias is needed.
+// asr) already match the enum case-insensitively, so no alias is needed.
 // Returns the input unchanged when it isn't an alias.
 func canonicalModelType(t string) string {
 	if strings.EqualFold(strings.TrimSpace(t), "chat") {
@@ -66,13 +66,11 @@ type CreateService interface {
 }
 
 // frontendModelType maps the create enum to the server's /models/providers
-// "model_type" query vocabulary (KnowledgeQA→chat, VLLM→vllm; others lowercase).
+// "model_type" query vocabulary (KnowledgeQA→chat; others lowercase).
 func frontendModelType(t string) string {
 	switch t {
 	case string(sdk.ModelTypeKnowledgeQA):
 		return "chat"
-	case string(sdk.ModelTypeVLLM):
-		return "vllm"
 	default:
 		return strings.ToLower(t)
 	}
@@ -83,7 +81,7 @@ func NewCmdCreate(f *cmdutil.Factory) *cobra.Command {
 	opts := &CreateOptions{}
 	cmd := &cobra.Command{
 		Use:   "create <name>",
-		Short: "Register a model (embedding / rerank / chat / VLLM / ASR)",
+		Short: "Register a model (embedding / rerank / chat / ASR)",
 		Long: `Register a model on the server so it can back a knowledge base's embedding /
 summary config (see 'weknora kb config set') or an agent (--model).
 
@@ -103,7 +101,7 @@ Two modes:
                    --base-url defaults to that provider's URL for the type when
                    omitted.
 
---type accepts the server's term "chat" for KnowledgeQA (embedding/rerank/vllm/
+--type accepts the server's term "chat" for KnowledgeQA (embedding/rerank/
 asr match the enum directly). Embedding models take --dimension. Pipe the
 provider key via --api-key-stdin so it never lands in argv/history. Anything
 else goes through repeatable --param key=value.`,
@@ -178,7 +176,7 @@ else goes through repeatable --param key=value.`,
 	cmdutil.AddFormatFlag(cmd, modelCreateFields...)
 	cmdutil.AddDryRunFlag(cmd, &opts.DryRun)
 	cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
-		UsedFor:       "register a model (embedding/rerank/chat/VLLM/ASR) so a KB or agent can use it; capture .data.id to pass to `weknora kb config set` / `agent create --model`.",
+		UsedFor:       "register a model (embedding/rerank/chat/ASR) so a KB or agent can use it; capture .data.id to pass to `weknora kb config set` / `agent create --model`.",
 		RequiredFlags: []string{"<name> (positional)", "--type", "--source (local|remote)", "--provider (when --source remote)"},
 		Examples: []string{
 			`weknora model create nomic-embed-text --type Embedding --source local --dimension 768   # Ollama (server pulls it)`,

cli/cmd/model/list.go

@@ -36,7 +36,7 @@ var modelSourceValues = cmdutil.EnumStrings(sdk.AllModelSources())
 // ListOptions captures `model list` filter flag state.
 type ListOptions struct {
 	// Type / Source, when set, restrict output to models of that type
-	// (Embedding, Rerank, KnowledgeQA, VLLM, ASR) or provider (local, openai,
+	// (Embedding, Rerank, KnowledgeQA, ASR) or provider (local, openai,
 	// …), matched case-insensitively. Empty shows everything.
 	Type   string
 	Source string
@@ -58,7 +58,7 @@ func NewCmdList(f *cmdutil.Factory) *cobra.Command {
 		Use:   "list",
 		Short: "List models configured on the server",
 		Long: `List the models configured on the server, sorted by type then name. Pass
---type to restrict to one model type (Embedding, Rerank, KnowledgeQA, VLLM, ASR).`,
+--type to restrict to one model type (Embedding, Rerank, KnowledgeQA, ASR).`,
 		Args: cobra.NoArgs,
 		RunE: func(c *cobra.Command, _ []string) error {
 			fopts, err := cmdutil.CheckFormatFlag(c)
@@ -78,7 +78,7 @@ func NewCmdList(f *cmdutil.Factory) *cobra.Command {
 			return runList(c.Context(), opts, fopts, cli)
 		},
 	}
-	cmd.Flags().StringVar(&opts.Type, "type", "", "Only show models of this type (Embedding, Rerank, KnowledgeQA, VLLM, ASR)")
+	cmd.Flags().StringVar(&opts.Type, "type", "", "Only show models of this type (Embedding, Rerank, KnowledgeQA, ASR)")
 	cmd.Flags().StringVar(&opts.Source, "source", "", "Only show models from this provider (local, remote, openai, aliyun, …)")
 	cmd.Flags().IntVarP(&opts.Limit, "limit", "L", 30, "Maximum results to return — client-side cap; meta.has_more/total_count report the full size (1..10000)")
 	cmdutil.AddFormatFlag(cmd, modelListFields...)

client/model.go

@@ -16,8 +16,7 @@ type ModelType string
 const (
 	ModelTypeEmbedding   ModelType = "Embedding"   // Embedding model
 	ModelTypeRerank      ModelType = "Rerank"      // Rerank model
-	ModelTypeKnowledgeQA ModelType = "KnowledgeQA" // KnowledgeQA model
-	ModelTypeVLLM        ModelType = "VLLM"        // VLLM model
+	ModelTypeKnowledgeQA ModelType = "KnowledgeQA" // KnowledgeQA model (vision rides input modalities)
 	ModelTypeASR         ModelType = "ASR"         // ASR (Automatic Speech Recognition) model
 )
 
@@ -26,7 +25,7 @@ const (
 // re-typing the string set, so they can't drift from the SDK.
 func AllModelTypes() []ModelType {
 	return []ModelType{
-		ModelTypeEmbedding, ModelTypeRerank, ModelTypeKnowledgeQA, ModelTypeVLLM, ModelTypeASR,
+		ModelTypeEmbedding, ModelTypeRerank, ModelTypeKnowledgeQA, ModelTypeASR,
 	}
 }
 
@@ -215,7 +214,7 @@ type ModelProviderListResponse struct {
 }
 
 // ListModelProviders retrieves the list of supported model providers.
-// modelType is optional and can be used to filter by type: "chat", "embedding", "rerank", "vllm".
+// modelType is optional and can be used to filter by type: "chat", "embedding", "rerank", "asr".
 func (c *Client) ListModelProviders(ctx context.Context, modelType string) ([]ModelProvider, error) {
 	var queryParams url.Values
 	if modelType != "" {

frontend/src/api/agent/index.ts

@@ -47,6 +47,7 @@ export interface CustomAgentConfig {
   temperature?: number;
   max_completion_tokens?: number;   // 0 = 跟随系统默认（快速问答 2048；智能推理 4096，绑沙箱可写文件时 24576）。大于 0 为自定义上限
   thinking?: boolean;                      // 是否启用思考模式（支持扩展思考的模型）
+  thinking_level?: string;               // 思考档位（空 = 跟随模型默认；开关为 config.thinking）
   citation_enabled?: boolean;        // 是否在最终回答中输出知识库/网页来源引用（默认开启）
 
   // ===== Agent模式设置 =====
@@ -135,6 +136,18 @@ export interface CustomAgentConfig {
   // 意图提示词：非检索意图（问候、闲聊等）时覆盖主系统提示词
   intent_prompts?: Record<string, string>;
 
+  // ===== 上下文模板 / 检索历史 / 数据分析 / FAQ / 联网抓取 / 查询理解 =====
+  // （后端 custom_agent.go 全量替换 config——按本接口从零构造会清零这些
+  // 字段，2026-09-13 审查补齐镜像；context_template_id 声明见上方模型设置组）
+  retain_retrieval_history?: boolean;
+  data_analysis_enabled?: boolean;
+  faq_priority_enabled?: boolean;
+  faq_direct_answer_threshold?: number;
+  faq_score_boost?: number;
+  web_fetch_enabled?: boolean;
+  web_fetch_top_n?: number;
+  query_understand_model_id?: string;
+
   // ===== 已废弃字段（保留兼容）=====
   welcome_message?: string;
   question_suggestions?: QuestionSuggestionConfig;

frontend/src/api/chat/streame.ts

@@ -26,28 +26,26 @@ interface StreamOptions {
 }
 
 export function useStream() {
-  // 响应式状态
-  const output = ref('')              // 显示内容
+  // 响应式状态（output/isLoading 曾是有写无读的死状态、buffer 是只进不读的
+  // 跨流死缓冲——随流累积，2026-09-13 审查删除；消费者只取下方 return 的键）
   const isStreaming = ref(false)      // 流状态
-  const isLoading = ref(false)        // 初始加载
   const error = ref<string | null>(null)// 错误信息
   const lastStreamRequest = ref<StreamRequestMeta | null>(null)
   let controller = new AbortController()
   let streamGeneration = 0
 
-  // 流式渲染缓冲
-  let buffer: string[] = []
-  let renderTimer: number | null = null
-
   // 启动流式请求
-  const startStream = async (params: { session_id: any; query: any; knowledge_base_ids?: string[]; knowledge_ids?: string[]; tag_ids?: string[]; agent_enabled?: boolean; agent_id?: string; agent_source_tenant_id?: string | number; web_search_enabled?: boolean; local_browser_enabled?: boolean; summary_model_id?: string; mcp_service_ids?: string[]; skill_names?: string[]; mentioned_items?: Array<{id: string; name: string; type: string; kb_type?: string; kb_id?: string; kb_name?: string; service_id?: string; skill_name?: string}>; images?: Array<{data: string}>; attachment_uploads?: Array<{data: string; file_name: string; file_size: number}>; attachment_ids?: string[]; suggestion_attribution?: { suggestion_set_id: string; question_id: string }; method: string; url: string; embed_token?: string; embed_session_sig?: string; embed_visitor_id?: string }) => {
+  const startStream = async (params: { session_id: any; query: any; knowledge_base_ids?: string[]; knowledge_ids?: string[]; tag_ids?: string[]; agent_enabled?: boolean; agent_id?: string; agent_source_tenant_id?: string | number; web_search_enabled?: boolean; local_browser_enabled?: boolean; summary_model_id?: string; thinking_level?: string; thinking?: boolean; mcp_service_ids?: string[]; skill_names?: string[]; mentioned_items?: Array<{id: string; name: string; type: string; kb_type?: string; kb_id?: string; kb_name?: string; service_id?: string; skill_name?: string}>; images?: Array<{data: string}>; attachment_uploads?: Array<{data: string; file_name: string; file_size: number}>; attachment_ids?: string[]; suggestion_attribution?: { suggestion_set_id: string; question_id: string }; method: string; url: string; embed_token?: string; embed_session_sig?: string; embed_visitor_id?: string }) => {
     const myGeneration = ++streamGeneration
+    // 终止在途旧流（2026-09-13 审查）：此前 generation guard 只丢 UI 渲染，
+    // 旧连接仍在耗网络与上游 tokens——先 abort 旧 controller 再换新；
+    // 旧流的 onclose/catch 需校验 generation，防止清理动作杀死新流。
+    controller.abort()
+    controller = new AbortController()
     const streamAbort = controller
     // 重置状态
-    output.value = '';
     error.value = null;
     isStreaming.value = true;
-    isLoading.value = true;
 
     // 获取API配置
     const apiUrl = getApiBaseUrl();
@@ -137,6 +135,13 @@ export function useStream() {
       if (params.images !== undefined && params.images.length > 0) {
         postBody.images = params.images;
       }
+      // 会话级思考覆盖（design §8.1.3）：空 = 跟随智能体/模型默认，不发送
+      if (params.thinking !== undefined) {
+        postBody.thinking = params.thinking;
+      }
+      if (params.thinking_level) {
+        postBody.thinking_level = params.thinking_level;
+      }
       // Include attachment_uploads if provided (documents, audio, etc.)
       if (params.attachment_uploads !== undefined && params.attachment_uploads.length > 0) {
         postBody.attachment_uploads = params.attachment_uploads;
@@ -183,20 +188,26 @@ export function useStream() {
           if (res.status === 401) throw new StreamAuthError(res.status);
           if (!res.ok) throw new Error(`HTTP ${res.status}`);
           console.log(`[TTFB] response:headers request_id=${requestID} elapsed_ms=${(performance.now() - sentAt).toFixed(1)}`);
-          isLoading.value = false;
         },
 
         onmessage: (ev) => {
           if (myGeneration !== streamGeneration) return
-          const parsed = JSON.parse(ev.data);
+          // 坏帧跳过（2026-09-13 审查）：裸 JSON.parse 的一帧异常会 reject
+          // 整条流；SSE 语义本可跳过坏帧续传。
+          let parsed: any;
+          try {
+            parsed = JSON.parse(ev.data);
+          } catch {
+            console.warn('[stream] skip non-JSON SSE frame:', String(ev.data).slice(0, 120));
+            return;
+          }
           // Log first answer chunk for end-to-end TTFB measurement.
           // Filter by event type so non-answer events (references, tool
           // calls, etc.) don't count as the "first token" arrival.
           if (!firstAnswerLogged && (parsed?.response_type === 'answer' || parsed?.type === 'answer')) {
             firstAnswerLogged = true;
             console.log(`[TTFB] response:first_answer request_id=${requestID} elapsed_ms=${(performance.now() - sentAt).toFixed(1)}`);
           }
-          buffer.push(parsed); // 数据存入缓冲
           // 执行自定义处理
           if (chunkHandler) {
             chunkHandler(parsed);
@@ -209,7 +220,8 @@ export function useStream() {
         },
 
         onclose: () => {
-          stopStream();
+          // generation 守卫：被新流 abort 的旧连接走到这里时不得清理新流
+          if (myGeneration === streamGeneration) stopStream();
         },
       });
 
@@ -227,8 +239,11 @@ export function useStream() {
         reloginMessage: i18n.global.t('error.pleaseRelogin'),
       });
     } catch (err) {
-      error.value = err instanceof Error ? err.message : String(err)
-      stopStream()
+      // generation 守卫：旧流被 abort 的报错不得写入新流的 error 状态
+      if (myGeneration === streamGeneration) {
+        error.value = err instanceof Error ? err.message : String(err)
+        stopStream()
+      }
     }
   }
 
@@ -245,16 +260,13 @@ export function useStream() {
     controller.abort();
     controller = new AbortController(); // 重置控制器（如需重新发起）
     isStreaming.value = false;
-    isLoading.value = false;
   }
 
   // 组件卸载时自动清理
   onUnmounted(stopStream)
 
   return {
-    output,          // 显示内容
     isStreaming,     // 是否在流式传输中
-    isLoading,       // 初始连接状态
     error,
     lastStreamRequest,
     onChunk,