Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.
Go agentagenticaichatbotdsh-pluginembeddingsevaluationgenerative-aigolangknowledge-basellmmulti-tenantollamaopenaiquestion-answeringragrerankingsemantic-searchvector-searchwiki
fix(models): show usage details when deletion is blocked (#2975)
leon4z988cbb03305e
diff --git a/docs/api/model.md b/docs/api/model.mdindex 61f6a1652..9a8b16e7c 100644--- a/docs/api/model.md+++ b/docs/api/model.md@@ -436,7 +436,29 @@ curl --location --request DELETE 'http://localhost:8080/api/v1/models/8fdc464d-8}```-404 表示模型不存在。+如果知识库、智能体或当前空间的长期记忆仍引用该模型,接口保持 HTTP 400,并返回专用错误码 `2300` 和结构化引用详情。例如:++```json+{+ "success": false,+ "error": {+ "code": 2300,+ "message": "model is used by 2 knowledge base(s); reconfigure or remove those references before deleting",+ "details": {+ "knowledge_bases": [+ {"id": "kb-1", "name": "Product docs", "bindings": ["vlm_model"]},+ {"id": "kb-2", "name": "Engineering", "bindings": ["vlm_model"]}+ ],+ "agents": [],+ "long_term_memory": {"bindings": []},+ "knowledge_base_total": 2,+ "agent_total": 0+ }+ }+}+```++`bindings` 是稳定的配置类型标识:知识库可能返回 `embedding_model`、`summary_model`、`image_processing_model`、`vlm_model`、`asr_model`、`wiki_synthesis_model`;智能体可能返回 `chat_model`、`rerank_model`、`vlm_model`、`asr_model`、`query_understand_model`、`follow_up_model`;长期记忆可能返回 `embedding_model`、`extract_model`。同一对象的多处引用会合并到一个 `bindings` 数组。`knowledge_bases` / `agents` 最多各返回 50 条;未截断的引用数在 `knowledge_base_total` / `agent_total`。404 表示模型不存在。## 参数说明diff --git a/docs/docs.go b/docs/docs.goindex 2ba0a205d..6037c0e27 100644--- a/docs/docs.go+++ b/docs/docs.go@@ -10421,6 +10421,12 @@ const docTemplate = `{"additionalProperties": true}},+ "400": {+ "description": "模型仍被知识库、智能体或长期记忆引用",+ "schema": {+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"+ }+ },"404": {"description": "模型不存在","schema": {@@ -17042,7 +17048,8 @@ const docTemplate = `{2102,2103,2200,- 2201+ 2201,+ 2300],"x-enum-varnames": ["ErrBadRequest",@@ -17067,7 +17074,8 @@ const docTemplate = `{"ErrAgentInvalidMaxIterations","ErrAgentInvalidTemperature","ErrVectorStoreBindingInvalid",- "ErrVectorStoreUnavailable"+ "ErrVectorStoreUnavailable",+ "ErrModelInUse"]},"github_com_Tencent_WeKnora_internal_infrastructure_chunker.DocProfile": {diff --git a/docs/swagger.json b/docs/swagger.jsonindex 6d55c4293..6d695c8de 100644--- a/docs/swagger.json+++ b/docs/swagger.json@@ -10414,6 +10414,12 @@"additionalProperties": true}},+ "400": {+ "description": "模型仍被知识库、智能体或长期记忆引用",+ "schema": {+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"+ }+ },"404": {"description": "模型不存在","schema": {@@ -17035,7 +17041,8 @@2102,2103,2200,- 2201+ 2201,+ 2300],"x-enum-varnames": ["ErrBadRequest",@@ -17060,7 +17067,8 @@"ErrAgentInvalidMaxIterations","ErrAgentInvalidTemperature","ErrVectorStoreBindingInvalid",- "ErrVectorStoreUnavailable"+ "ErrVectorStoreUnavailable",+ "ErrModelInUse"]},"github_com_Tencent_WeKnora_internal_infrastructure_chunker.DocProfile": {@@ -25054,4 +25062,4 @@"in": "header"}}-}\ No newline at end of file+}diff --git a/docs/swagger.yaml b/docs/swagger.yamlindex 584de6834..411b3110c 100644--- a/docs/swagger.yaml+++ b/docs/swagger.yaml@@ -116,6 +116,7 @@ definitions:- 2103- 2200- 2201+ - 2300type: integerx-enum-varnames:- ErrBadRequest@@ -141,6 +142,7 @@ definitions:- ErrAgentInvalidTemperature- ErrVectorStoreBindingInvalid- ErrVectorStoreUnavailable+ - ErrModelInUsegithub_com_Tencent_WeKnora_internal_infrastructure_chunker.DocProfile:properties:all_caps_short_line_count:@@ -12844,6 +12846,10 @@ paths:schema:additionalProperties: truetype: object+ "400":+ description: 模型仍被知识库、智能体或长期记忆引用+ schema:+ $ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError'"404":description: 模型不存在schema:diff --git a/docs/swagger_contract_test.go b/docs/swagger_contract_test.goindex e701ee62e..75349c501 100644--- a/docs/swagger_contract_test.go+++ b/docs/swagger_contract_test.go@@ -9,12 +9,14 @@ import ("gopkg.in/yaml.v3")-func TestKnowledgeSearchRouteContract(t *testing.T) {- tests := []struct {- name string- loadSpec func(t *testing.T) []byte- parse func([]byte, any) error- }{+type swaggerDocumentCase struct {+ name string+ loadSpec func(t *testing.T) []byte+ parse func([]byte, any) error+}++func swaggerDocuments() []swaggerDocumentCase {+ return []swaggerDocumentCase{{name: "registered document",loadSpec: func(t *testing.T) []byte {@@ -40,14 +42,24 @@ func TestKnowledgeSearchRouteContract(t *testing.T) {parse: yaml.Unmarshal,},}+}- for _, tt := range tests {+func TestKnowledgeSearchRouteContract(t *testing.T) {+ for _, tt := range swaggerDocuments() {t.Run(tt.name, func(t *testing.T) {assertKnowledgeSearchRouteContract(t, tt.loadSpec(t), tt.parse)})}}+func TestModelDeleteUsageContract(t *testing.T) {+ for _, tt := range swaggerDocuments() {+ t.Run(tt.name, func(t *testing.T) {+ assertModelDeleteUsageContract(t, tt.loadSpec(t), tt.parse)+ })+ }+}+func readSwaggerFile(t *testing.T, name string) []byte {t.Helper()data, err := os.ReadFile(name)@@ -80,3 +92,62 @@ func assertKnowledgeSearchRouteContract(t *testing.T, data []byte, parse func([]}}}++func assertModelDeleteUsageContract(t *testing.T, data []byte, parse func([]byte, any) error) {+ t.Helper()+ var spec struct {+ Paths map[string]map[string]struct {+ Responses map[string]any `json:"responses" yaml:"responses"`+ } `json:"paths" yaml:"paths"`+ Definitions map[string]map[string]any `json:"definitions" yaml:"definitions"`+ }+ if err := parse(data, &spec); err != nil {+ t.Fatalf("parse generated Swagger document: %v", err)+ }++ models, ok := spec.Paths["/models/{id}"]+ if !ok {+ t.Fatal("generated Swagger document does not expose /models/{id}")+ }+ deleteOperation, ok := models["delete"]+ if !ok {+ t.Fatal("generated Swagger document does not expose DELETE /models/{id}")+ }+ if _, ok := deleteOperation.Responses["400"]; !ok {+ t.Fatal("model DELETE Swagger contract does not document the model-in-use 400 response")+ }++ const errorCodeDefinition = "github_com_Tencent_WeKnora_internal_errors.ErrorCode"+ errorCodes, ok := spec.Definitions[errorCodeDefinition]+ if !ok {+ t.Fatalf("generated Swagger document does not expose %s", errorCodeDefinition)+ }+ enum, ok := errorCodes["enum"].([]any)+ if !ok {+ t.Fatalf("generated Swagger ErrorCode enum has unexpected shape: %#v", errorCodes["enum"])+ }+ enumVarNames, ok := errorCodes["x-enum-varnames"].([]any)+ if !ok {+ t.Fatalf("generated Swagger ErrorCode names have unexpected shape: %#v", errorCodes["x-enum-varnames"])+ }+ for i, value := range enum {+ if swaggerInteger(value) == 2300 {+ if i >= len(enumVarNames) || enumVarNames[i] != "ErrModelInUse" {+ t.Fatalf("error code 2300 must align with ErrModelInUse, got names=%v", enumVarNames)+ }+ return+ }+ }+ t.Fatal("generated Swagger ErrorCode enum does not include model-in-use code 2300")+}++func swaggerInteger(value any) int {+ switch number := value.(type) {+ case int:+ return number+ case float64:+ return int(number)+ default:+ return 0+ }+}diff --git a/frontend/src/api/model/index.ts b/frontend/src/api/model/index.tsindex e18d9657a..a5f02c2c6 100644--- a/frontend/src/api/model/index.ts+++ b/frontend/src/api/model/index.ts@@ -1,5 +1,8 @@import { get, post, postUpload, put, del } from '../../utils/request';import i18n from '@/i18n'+import { ModelInUseError, modelInUseErrorFromRequest } from './modelUsage'++export * from './modelUsage'const t = (key: string) => i18n.global.t(key)@@ -135,11 +138,25 @@ export function deleteModel(id: string): Promise<void> {if (response.success) {resolve();} else {+ const conflict = modelInUseErrorFromRequest(response)+ if (conflict) {+ reject(conflict)+ return+ }reject(new Error(response.message || t('error.model.deleteFailed')));}}).catch((error: any) => {console.error('Failed to delete model:', error);+ if (error instanceof ModelInUseError) {+ reject(error)+ return+ }+ const conflict = modelInUseErrorFromRequest(error)+ if (conflict) {+ reject(conflict)+ return+ }reject(error);});});diff --git a/frontend/src/api/model/modelUsage.test.ts b/frontend/src/api/model/modelUsage.test.tsnew file mode 100644index 000000000..bbd195b9e--- /dev/null+++ b/frontend/src/api/model/modelUsage.test.ts@@ -0,0 +1,138 @@+import assert from 'node:assert/strict'+import test from 'node:test'++import {+ MODEL_IN_USE_ERROR_CODE,+ ModelInUseError,+ modelInUseErrorFromRequest,+ modelUsageAgentSection,+ modelUsageBindingI18nKey,+ modelUsageKnowledgeBaseSection,+ modelUsageListTruncated,+ modelUsageResourceCount,+ modelUsageResourceRoute,+ parseModelUsageDetails,+} from './modelUsage'++const details = {+ knowledge_bases: [+ { id: 'kb-1', name: 'Product docs', bindings: ['vlm_model'] },+ { id: 'kb-2', name: 'Engineering', bindings: ['vlm_model'] },+ ],+ agents: [+ { id: 'agent-1', name: 'Support', bindings: ['chat_model', 'follow_up_model'] },+ ],+ long_term_memory: { bindings: ['extract_model'] },+ knowledge_base_total: 2,+ agent_total: 1,+}++test('parses grouped model usage details without dropping multiple bindings', () => {+ assert.deepEqual(parseModelUsageDetails(details), details)+})++test('fills missing totals from the listed collections', () => {+ const { knowledge_base_total, agent_total, ...withoutTotals } = details+ assert.deepEqual(parseModelUsageDetails(withoutTotals), details)+ assert.equal(knowledge_base_total, 2)+ assert.equal(agent_total, 1)+})++test('keeps untruncated totals when the listed collections are capped', () => {+ const parsed = parseModelUsageDetails({+ ...details,+ knowledge_base_total: 80,+ agent_total: 12,+ })+ assert.equal(parsed?.knowledge_base_total, 80)+ assert.equal(parsed?.agent_total, 12)+ assert.equal(modelUsageResourceCount(parsed!.knowledge_bases, parsed!.knowledge_base_total), 80)+ assert.equal(modelUsageListTruncated(parsed!.knowledge_bases, parsed!.knowledge_base_total), true)+ assert.equal(modelUsageListTruncated(parsed!.agents, parsed!.agent_total), true)+})++test('recognizes only the dedicated model-in-use code with a valid payload', () => {+ const conflict = modelInUseErrorFromRequest({+ status: 400,+ success: false,+ error: {+ code: MODEL_IN_USE_ERROR_CODE,+ message: 'backwards-compatible server message',+ details,+ },+ })++ assert.ok(conflict instanceof ModelInUseError)+ assert.deepEqual(conflict.details, details)+ assert.equal(modelInUseErrorFromRequest({ error: { code: 1000, details } }), null)+})++test('rejects malformed details instead of guessing from the server message', () => {+ assert.equal(parseModelUsageDetails({ knowledge_bases: [], agents: [] }), null)+ assert.equal(parseModelUsageDetails({+ knowledge_bases: [],+ agents: [],+ long_term_memory: { bindings: [] },+ }), null)+ assert.equal(parseModelUsageDetails({+ knowledge_bases: [{ id: 'kb-1', name: 'Docs', bindings: [] }],+ agents: [],+ long_term_memory: { bindings: [] },+ }), null)+ assert.equal(parseModelUsageDetails({+ knowledge_bases: [{ id: 'kb-1', name: 'Docs', bindings: 'vlm_model' }],+ agents: [],+ long_term_memory: { bindings: [] },+ }), null)+ assert.equal(modelInUseErrorFromRequest({+ error: {+ code: MODEL_IN_USE_ERROR_CODE,+ message: 'model is used by 1 knowledge base(s)',+ details: null,+ },+ }), null)+})++test('keeps navigation and localization stable for all resource kinds', () => {+ assert.deepEqual(+ modelUsageResourceRoute('knowledge_base', 'kb/with slash'),+ { path: '/platform/knowledge-bases/kb%2Fwith%20slash' },+ )+ assert.deepEqual(+ modelUsageResourceRoute('agent', 'agent-1'),+ { path: '/platform/agents', query: { edit: 'agent-1', section: 'model' } },+ )+ assert.deepEqual(+ modelUsageResourceRoute('agent', 'agent-1', ['vlm_model']),+ { path: '/platform/agents', query: { edit: 'agent-1', section: 'multimodal' } },+ )+ assert.deepEqual(+ modelUsageResourceRoute('agent', 'agent-1', ['follow_up_model']),+ { path: '/platform/agents', query: { edit: 'agent-1', section: 'suggestions' } },+ )+ assert.equal(modelUsageBindingI18nKey('vlm_model'), 'modelSettings.usage.bindings.vlm_model')+ assert.equal(modelUsageBindingI18nKey('future_binding'), 'modelSettings.usage.bindings.unknown')+})++test('maps knowledge-base bindings to the configuration section that owns them', () => {+ assert.equal(modelUsageKnowledgeBaseSection(['embedding_model']), 'models')+ assert.equal(modelUsageKnowledgeBaseSection(['summary_model']), 'models')+ assert.equal(modelUsageKnowledgeBaseSection(['wiki_synthesis_model']), 'models')+ assert.equal(modelUsageKnowledgeBaseSection(['image_processing_model']), 'multimodal')+ assert.equal(modelUsageKnowledgeBaseSection(['vlm_model']), 'multimodal')+ assert.equal(modelUsageKnowledgeBaseSection(['asr_model']), 'asr')+ assert.equal(modelUsageKnowledgeBaseSection(['future_binding']), 'models')+ assert.equal(modelUsageKnowledgeBaseSection(['summary_model', 'vlm_model']), 'models')+})++test('maps agent bindings to the configuration section that owns them', () => {+ assert.equal(modelUsageAgentSection(['chat_model']), 'model')+ assert.equal(modelUsageAgentSection(['rerank_model']), 'model')+ assert.equal(modelUsageAgentSection(['query_understand_model']), 'model')+ assert.equal(modelUsageAgentSection(['vlm_model']), 'multimodal')+ assert.equal(modelUsageAgentSection(['asr_model']), 'multimodal')+ assert.equal(modelUsageAgentSection(['follow_up_model']), 'suggestions')+ assert.equal(modelUsageAgentSection(['future_binding']), 'model')+ assert.equal(modelUsageAgentSection(['chat_model', 'vlm_model']), 'model')+ assert.equal(modelUsageAgentSection(['vlm_model', 'follow_up_model']), 'multimodal')+})diff --git a/frontend/src/api/model/modelUsage.ts b/frontend/src/api/model/modelUsage.tsnew file mode 100644index 000000000..94bc22716--- /dev/null+++ b/frontend/src/api/model/modelUsage.ts@@ -0,0 +1,182 @@+export const MODEL_IN_USE_ERROR_CODE = 2300++export const KNOWN_MODEL_USAGE_BINDINGS = [+ 'embedding_model',+ 'summary_model',+ 'image_processing_model',+ 'vlm_model',+ 'asr_model',+ 'wiki_synthesis_model',+ 'chat_model',+ 'rerank_model',+ 'query_understand_model',+ 'follow_up_model',+ 'extract_model',+] as const++export type KnownModelUsageBinding = typeof KNOWN_MODEL_USAGE_BINDINGS[number]++export interface ModelUsageResource {+ id: string+ name: string+ bindings: string[]+}++export interface ModelUsageDetails {+ knowledge_bases: ModelUsageResource[]+ agents: ModelUsageResource[]+ long_term_memory: {+ bindings: string[]+ }+ knowledge_base_total: number+ agent_total: number+}++export class ModelInUseError extends Error {+ readonly details: ModelUsageDetails++ constructor(details: ModelUsageDetails) {+ super('model is in use')+ this.name = 'ModelInUseError'+ this.details = details+ }+}++type UnknownRecord = Record<string, unknown>++function isRecord(value: unknown): value is UnknownRecord {+ return typeof value === 'object' && value !== null && !Array.isArray(value)+}++function parseBindings(value: unknown): string[] | null {+ if (!Array.isArray(value) || value.some(binding => typeof binding !== 'string' || binding.trim() === '')) {+ return null+ }+ return [...value]+}++function parseResources(value: unknown): ModelUsageResource[] | null {+ if (!Array.isArray(value)) return null++ const resources: ModelUsageResource[] = []+ for (const item of value) {+ if (!isRecord(item) || typeof item.id !== 'string' || item.id.trim() === '' || typeof item.name !== 'string') {+ return null+ }+ const bindings = parseBindings(item.bindings)+ if (!bindings || bindings.length === 0) return null+ resources.push({ id: item.id, name: item.name, bindings })+ }+ return resources+}++function parseTotal(value: unknown, listed: number): number {+ if (typeof value === 'number' && Number.isFinite(value) && value >= listed) {+ return Math.floor(value)+ }+ return listed+}++export function parseModelUsageDetails(value: unknown): ModelUsageDetails | null {+ if (!isRecord(value) || !isRecord(value.long_term_memory)) return null++ const knowledgeBases = parseResources(value.knowledge_bases)+ const agents = parseResources(value.agents)+ const memoryBindings = parseBindings(value.long_term_memory.bindings)+ if (!knowledgeBases || !agents || !memoryBindings) return null++ const details: ModelUsageDetails = {+ knowledge_bases: knowledgeBases,+ agents,+ long_term_memory: { bindings: memoryBindings },+ knowledge_base_total: parseTotal(value.knowledge_base_total, knowledgeBases.length),+ agent_total: parseTotal(value.agent_total, agents.length),+ }+ if (knowledgeBases.length === 0 && agents.length === 0 && memoryBindings.length === 0) {+ return null+ }+ return details+}++export function modelInUseErrorFromRequest(error: unknown): ModelInUseError | null {+ if (!isRecord(error) || !isRecord(error.error) || error.error.code !== MODEL_IN_USE_ERROR_CODE) {+ return null+ }+ const details = parseModelUsageDetails(error.error.details)+ return details ? new ModelInUseError(details) : null+}++const knownBindings = new Set<string>(KNOWN_MODEL_USAGE_BINDINGS)++export function modelUsageBindingI18nKey(binding: string): string {+ const key = knownBindings.has(binding) ? binding : 'unknown'+ return `modelSettings.usage.bindings.${key}`+}++export function modelUsageResourceCount(resources: readonly ModelUsageResource[], total?: number): number {+ return typeof total === 'number' && Number.isFinite(total) && total >= resources.length+ ? Math.floor(total)+ : resources.length+}++export function modelUsageListTruncated(resources: readonly ModelUsageResource[], total?: number): boolean {+ return modelUsageResourceCount(resources, total) > resources.length+}++export type ModelUsageResourceKind = 'knowledge_base' | 'agent'++export type KnowledgeBaseModelUsageSection = 'models' | 'multimodal' | 'asr'++export type AgentModelUsageSection = 'model' | 'multimodal' | 'suggestions'++const knowledgeBaseUsageSections: Partial<Record<KnownModelUsageBinding, KnowledgeBaseModelUsageSection>> = {+ embedding_model: 'models',+ summary_model: 'models',+ wiki_synthesis_model: 'models',+ image_processing_model: 'multimodal',+ vlm_model: 'multimodal',+ asr_model: 'asr',+}++const agentUsageSections: Partial<Record<KnownModelUsageBinding, AgentModelUsageSection>> = {+ chat_model: 'model',+ rerank_model: 'model',+ query_understand_model: 'model',+ vlm_model: 'multimodal',+ asr_model: 'multimodal',+ follow_up_model: 'suggestions',+}++export function modelUsageKnowledgeBaseSection(+ bindings: readonly string[],+): KnowledgeBaseModelUsageSection {+ for (const binding of bindings) {+ const section = knowledgeBaseUsageSections[binding as KnownModelUsageBinding]+ if (section) return section+ }+ return 'models'+}++export function modelUsageAgentSection(+ bindings: readonly string[],+): AgentModelUsageSection {+ for (const binding of bindings) {+ const section = agentUsageSections[binding as KnownModelUsageBinding]+ if (section) return section+ }+ return 'model'+}++export function modelUsageResourceRoute(+ kind: ModelUsageResourceKind,+ id: string,+ bindings: readonly string[] = [],+) {+ if (kind === 'knowledge_base') {+ return { path: `/platform/knowledge-bases/${encodeURIComponent(id)}` }+ }+ return {+ path: '/platform/agents',+ query: { edit: id, section: modelUsageAgentSection(bindings) },+ }+}diff --git a/frontend/src/components/AgentCreateContextualGuide.vue b/frontend/src/components/AgentCreateContextualGuide.vueindex d502b6528..2d4b93d38 100644--- a/frontend/src/components/AgentCreateContextualGuide.vue+++ b/frontend/src/components/AgentCreateContextualGuide.vue@@ -7,7 +7,7 @@import { computed, ref, watch } from 'vue'import SpotlightGuide from '@/components/SpotlightGuide.vue'import {- AGENT_EDITOR_FOCUS_SECTION_EVENT,+ focusAgentEditorSection,markContextualGuideDone,isContextualGuideDone,isGlobalUserGuideDone,@@ -21,76 +21,70 @@ const props = defineProps<{const active = ref(false)-const focusSection = (section: string) => {- window.dispatchEvent(- new CustomEvent(AGENT_EDITOR_FOCUS_SECTION_EVENT, { detail: { section } }),- )-}-const guideSteps = computed<SpotlightGuideStep[]>(() => {const steps: SpotlightGuideStep[] = [{key: 'mode',target: '[data-guide="agent-create-mode"]',placement: 'right',- before: () => focusSection('basic'),+ before: () => focusAgentEditorSection('basic'),},{key: 'agentType',target: '[data-guide="agent-create-agent-type"]',placement: 'right',- before: () => focusSection('basic'),+ before: () => focusAgentEditorSection('basic'),optional: true,},{key: 'name',target: '[data-guide="agent-create-name"]',placement: 'right',- before: () => focusSection('basic'),+ before: () => focusAgentEditorSection('basic'),},{key: 'navModel',target: '[data-guide="agent-editor-nav-model"]',placement: 'right',- before: () => focusSection('model'),+ before: () => focusAgentEditorSection('model'),},{key: 'model',target: '[data-guide="agent-create-model"]',placement: 'right',- before: () => focusSection('model'),+ before: () => focusAgentEditorSection('model'),},{key: 'navKnowledge',target: '[data-guide="agent-editor-nav-knowledge"]',placement: 'right',- before: () => focusSection('knowledge'),+ before: () => focusAgentEditorSection('knowledge'),},{key: 'knowledge',target: '[data-guide="agent-create-knowledge"]',placement: 'right',- before: () => focusSection('knowledge'),+ before: () => focusAgentEditorSection('knowledge'),},{key: 'navWebsearch',target: '[data-guide="agent-editor-nav-websearch"]',placement: 'right',- before: () => focusSection('websearch'),+ before: () => focusAgentEditorSection('websearch'),optional: true,},{key: 'navMultimodal',target: '[data-guide="agent-editor-nav-multimodal"]',placement: 'right',- before: () => focusSection('multimodal'),+ before: () => focusAgentEditorSection('multimodal'),optional: true,},{key: 'multimodal',target: '[data-guide="agent-create-multimodal"]',placement: 'right',- before: () => focusSection('multimodal'),+ before: () => focusAgentEditorSection('multimodal'),optional: true,},]@@ -100,7 +94,7 @@ const guideSteps = computed<SpotlightGuideStep[]>(() => {key: 'navTools',target: '[data-guide="agent-editor-nav-tools"]',placement: 'right',- before: () => focusSection('tools'),+ before: () => focusAgentEditorSection('tools'),optional: true,})}@@ -109,7 +103,7 @@ const guideSteps = computed<SpotlightGuideStep[]>(() => {key: 'submit',target: '[data-guide="agent-create-submit"]',placement: 'top',- before: () => focusSection('basic'),+ before: () => focusAgentEditorSection('basic'),interact: true,})diff --git a/frontend/src/components/KbCreateContextualGuide.vue b/frontend/src/components/KbCreateContextualGuide.vueindex d9a8a82ae..88ace311d 100644--- a/frontend/src/components/KbCreateContextualGuide.vue+++ b/frontend/src/components/KbCreateContextualGuide.vue@@ -7,7 +7,7 @@import { computed, ref, watch } from 'vue'import SpotlightGuide from '@/components/SpotlightGuide.vue'import {- KB_EDITOR_FOCUS_SECTION_EVENT,+ focusKbEditorSection,markContextualGuideDone,isContextualGuideDone,isGlobalUserGuideDone,@@ -22,25 +22,19 @@ const props = defineProps<{const active = ref(false)-const focusSection = (section: string) => {- window.dispatchEvent(- new CustomEvent(KB_EDITOR_FOCUS_SECTION_EVENT, { detail: { section } }),- )-}-const guideSteps = computed<SpotlightGuideStep[]>(() => {const steps: SpotlightGuideStep[] = [{key: 'type',target: '[data-guide="kb-create-type"]',placement: 'right',- before: () => focusSection('basic'),+ before: () => focusKbEditorSection('basic'),},{key: 'name',target: '[data-guide="kb-create-name"]',placement: 'right',- before: () => focusSection('basic'),+ before: () => focusKbEditorSection('basic'),},]@@ -49,7 +43,7 @@ const guideSteps = computed<SpotlightGuideStep[]>(() => {key: 'indexing',target: '[data-guide="kb-create-indexing"]',placement: 'right',- before: () => focusSection('basic'),+ before: () => focusKbEditorSection('basic'),})}@@ -58,13 +52,13 @@ const guideSteps = computed<SpotlightGuideStep[]>(() => {key: 'navModels',target: '[data-guide="kb-editor-nav-models"]',placement: 'right',- before: () => focusSection('models'),+ before: () => focusKbEditorSection('models'),},{key: 'llm',target: '[data-guide="kb-create-llm"]',placement: 'right',- before: () => focusSection('models'),+ before: () => focusKbEditorSection('models'),},)@@ -73,7 +67,7 @@ const guideSteps = computed<SpotlightGuideStep[]>(() => {key: 'embedding',target: '[data-guide="kb-create-embedding"]',placement: 'right',- before: () => focusSection('models'),+ before: () => focusKbEditorSection('models'),optional: true,})}@@ -84,42 +78,42 @@ const guideSteps = computed<SpotlightGuideStep[]>(() => {key: 'parser',target: '[data-guide="kb-editor-nav-parser"]',placement: 'right',- before: () => focusSection('parser'),+ before: () => focusKbEditorSection('parser'),optional: true,},{key: 'chunking',target: '[data-guide="kb-editor-nav-chunking"]',placement: 'right',- before: () => focusSection('chunking'),+ before: () => focusKbEditorSection('chunking'),optional: true,},{key: 'storage',target: '[data-guide="kb-editor-nav-storage"]',placement: 'right',- before: () => focusSection('storage'),+ before: () => focusKbEditorSection('storage'),optional: true,},{key: 'navMultimodal',target: '[data-guide="kb-editor-nav-multimodal"]',placement: 'right',- before: () => focusSection('multimodal'),+ before: () => focusKbEditorSection('multimodal'),optional: true,},{key: 'multimodalToggle',target: '[data-guide="kb-create-multimodal-toggle"]',placement: 'right',- before: () => focusSection('multimodal'),+ before: () => focusKbEditorSection('multimodal'),optional: true,},{key: 'multimodalVllm',target: '[data-guide="kb-create-multimodal-vllm"]',placement: 'right',- before: () => focusSection('multimodal'),+ before: () => focusKbEditorSection('multimodal'),optional: true,},)@@ -128,7 +122,7 @@ const guideSteps = computed<SpotlightGuideStep[]>(() => {key: 'faq',target: '[data-guide="kb-editor-nav-faq"]',placement: 'right',- before: () => focusSection('faq'),+ before: () => focusKbEditorSection('faq'),optional: true,})}@@ -137,7 +131,7 @@ const guideSteps = computed<SpotlightGuideStep[]>(() => {key: 'submit',target: '[data-guide="kb-create-submit"]',placement: 'top',- before: () => focusSection('basic'),+ before: () => focusKbEditorSection('basic'),interact: true,})diff --git a/frontend/src/components/modelSelectorFilter.test.ts b/frontend/src/components/modelSelectorFilter.test.tsindex 3397af189..c42138762 100644--- a/frontend/src/components/modelSelectorFilter.test.ts+++ b/frontend/src/components/modelSelectorFilter.test.ts@@ -1,10 +1,16 @@import assert from 'node:assert/strict'+import { readFileSync } from 'node:fs'import test from 'node:test'import type { ModelConfig } from '@/api/model'import { filterModelsByType } from './modelSelectorFilter.ts'+const selectorSource = readFileSync(new URL('./ModelSelector.vue', import.meta.url), 'utf8')+const kbEditorSource = readFileSync(new URL('../views/knowledge/KnowledgeBaseEditorModal.vue', import.meta.url), 'utf8')+const agentEditorSource = readFileSync(new URL('../views/agent/AgentEditorModal.vue', import.meta.url), 'utf8')+const modelSettingsSource = readFileSync(new URL('../views/settings/ModelSettings.vue', import.meta.url), 'utf8')+function model(overrides: Partial<ModelConfig> & Pick<ModelConfig, 'id' | 'type'>): ModelConfig {return {name: overrides.name ?? overrides.id!,@@ -15,8 +21,8 @@ function model(overrides: Partial<ModelConfig> & Pick<ModelConfig, 'id' | 'type'}const fixtures: ModelConfig[] = [- model({ id: 'vllm-1', type: 'VLLM' }),- model({ id: 'chat-vision', type: 'KnowledgeQA', parameters: { supports_vision: true } }),+ model({ id: 'vllm-1', name: 'MiniMax-M3', display_name: 'MiniMax M3', type: 'VLLM' }),+ model({ id: 'chat-vision', name: 'MiniMax-M3', display_name: 'MiniMax M3', type: 'KnowledgeQA', parameters: { supports_vision: true } }),model({ id: 'chat-text', type: 'KnowledgeQA' }),model({ id: 'embed-vision', type: 'Embedding', parameters: { supports_vision: true } }),model({ id: 'embed-1', type: 'Embedding' }),@@ -27,6 +33,23 @@ test('VLLM selector includes native VLLM and vision-capable chat models', () =>assert.deepEqual(ids, ['vllm-1', 'chat-vision'])})+test('VLLM selector keeps the standard model-name presentation without type suffixes', () => {+ assert.match(selectorSource, /:label="modelDisplayName\(model\)"/)+ assert.doesNotMatch(selectorSource, /modelOptionTypeLabel|modelOptionLabel|vlmOptionType/)+})++test('VLM selection, knowledge-base and agent saves, and deletion preserve the selected model ID', () => {+ assert.match(selectorSource, /:key="model\.id"[\s\S]*:value="model\.id"/)+ assert.match(selectorSource, /emit\('update:selectedModelId', value \|\| ''\)/)+ assert.match(kbEditorSource, /handleMultimodalVLLMChange[\s\S]*vllmModelId = modelId/)+ assert.match(kbEditorSource, /vlm_config = \{[\s\S]*model_id:[\s\S]*vllmModelId/)+ assert.match(agentEditorSource, /model-type="VLLM"[\s\S]*formData\.config\.vlm_model_id[\s\S]*formData\.config\.vlm_model_id = val/)+ assert.match(agentEditorSource, /updateAgent\(formData\.value\.id, formData\.value\)/)+ assert.match(modelSettingsSource, /@confirm="deleteModel\(model\._modelType, model\.id\)"/)+ assert.match(modelSettingsSource, /allModels\.value\.find\(m => m\.id === modelId\)/)+ assert.match(modelSettingsSource, /await deleteModelAPI\(modelId\)/)+})+test('VLLM selector excludes non-vision chat and other types even with supports_vision', () => {const ids = filterModelsByType(fixtures, 'VLLM')assert.ok(!ids.some((m) => m.id === 'chat-text'))diff --git a/frontend/src/config/contextualGuides.ts b/frontend/src/config/contextualGuides.tsindex a3c223cf2..5b1f575ee 100644--- a/frontend/src/config/contextualGuides.ts+++ b/frontend/src/config/contextualGuides.ts@@ -19,12 +19,18 @@ export type ContextualGuideTourId =| 'agentList'| 'agentCreate'-const focusKbEditorSection = (section: string) => {+export const focusKbEditorSection = (section: string) => {window.dispatchEvent(new CustomEvent(KB_EDITOR_FOCUS_SECTION_EVENT, { detail: { section } }),)}+export const focusAgentEditorSection = (section: string) => {+ window.dispatchEvent(+ new CustomEvent(AGENT_EDITOR_FOCUS_SECTION_EVENT, { detail: { section } }),+ )+}+const focusKbEditorBasic = () => focusKbEditorSection('basic')export interface ContextualGuideTourConfig {diff --git a/frontend/src/i18n/locales/en-US.ts b/frontend/src/i18n/locales/en-US.tsindex c58c47502..f42600963 100755--- a/frontend/src/i18n/locales/en-US.ts+++ b/frontend/src/i18n/locales/en-US.ts@@ -4671,6 +4671,29 @@ export default {},builtinTag: 'Built-in',confirmDelete: 'Delete model "{name}"?',+ usage: {+ title: 'Model cannot be deleted',+ description: 'Model "{name}" is still referenced by the following settings. Open each configuration and choose another model before deleting it.',+ knowledgeBases: 'Knowledge bases ({count})',+ agents: 'Agents ({count})',+ longTermMemory: 'Long-term memory',+ openConfiguration: 'Open settings',+ truncated: 'Showing the first {shown} of {total}',+ bindings: {+ embedding_model: 'Embedding model',+ summary_model: 'Summary model',+ image_processing_model: 'Image processing model',+ vlm_model: 'Vision model',+ asr_model: 'Speech recognition model',+ wiki_synthesis_model: 'Wiki synthesis model',+ chat_model: 'Chat model',+ rerank_model: 'Re-ranking model',+ query_understand_model: 'Query understanding model',+ follow_up_model: 'Follow-up model',+ extract_model: 'Memory extraction model',+ unknown: 'Other model setting'+ }+ },debug: {title: 'Model Test',description: 'Send a real request to a saved model and inspect the response',diff --git a/frontend/src/i18n/locales/ko-KR.ts b/frontend/src/i18n/locales/ko-KR.tsindex 65aa641aa..832d2ac92 100755--- a/frontend/src/i18n/locales/ko-KR.ts+++ b/frontend/src/i18n/locales/ko-KR.ts@@ -1976,6 +1976,29 @@ export default {copySuffix: ' 사본',builtinTag: '기본제공',confirmDelete: '모델 "{name}"을(를) 삭제하시겠습니까?',+ usage: {+ title: '모델을 삭제할 수 없습니다',+ description: '모델 "{name}"이(가) 다음 설정에서 사용 중입니다. 각 설정을 열어 다른 모델로 변경한 후 다시 삭제하세요.',+ knowledgeBases: '지식 베이스 ({count})',+ agents: '에이전트 ({count})',+ longTermMemory: '장기 메모리',+ openConfiguration: '설정 열기',+ truncated: '전체 {total}개 중 앞 {shown}개만 표시합니다',+ bindings: {+ embedding_model: 'Embedding 모델',+ summary_model: '요약 모델',+ image_processing_model: '이미지 처리 모델',+ vlm_model: '비전 모델',+ asr_model: '음성 인식 모델',+ wiki_synthesis_model: 'Wiki 종합 모델',+ chat_model: '대화 모델',+ rerank_model: '재정렬 모델',+ query_understand_model: '질의 이해 모델',+ follow_up_model: '후속 질문 모델',+ extract_model: '메모리 추출 모델',+ unknown: '기타 모델 설정'+ }+ },debug: {title: '모델 테스트',description: '구성된 모델에 실제 요청을 보내고 응답과 소요 시간을 확인합니다',diff --git a/frontend/src/i18n/locales/ru-RU.ts b/frontend/src/i18n/locales/ru-RU.tsindex 5382e9b40..1128cb574 100755--- a/frontend/src/i18n/locales/ru-RU.ts+++ b/frontend/src/i18n/locales/ru-RU.ts@@ -1976,6 +1976,29 @@ export default {copySuffix: ' копия',builtinTag: 'Встроенная',confirmDelete: 'Удалить модель «{name}»?',+ usage: {+ title: 'Модель нельзя удалить',+ description: 'Модель «{name}» используется в следующих настройках. Откройте каждую конфигурацию и выберите другую модель, затем повторите удаление.',+ knowledgeBases: 'Базы знаний ({count})',+ agents: 'Агенты ({count})',+ longTermMemory: 'Долговременная память',+ openConfiguration: 'Открыть настройки',+ truncated: 'Показаны первые {shown} из {total}',+ bindings: {+ embedding_model: 'Модель эмбеддингов',+ summary_model: 'Модель суммаризации',+ image_processing_model: 'Модель обработки изображений',+ vlm_model: 'Модель компьютерного зрения',+ asr_model: 'Модель распознавания речи',+ wiki_synthesis_model: 'Модель синтеза Wiki',+ chat_model: 'Диалоговая модель',+ rerank_model: 'Модель реранжирования',+ query_understand_model: 'Модель понимания запроса',+ follow_up_model: 'Модель уточняющих вопросов',+ extract_model: 'Модель извлечения памяти',+ unknown: 'Другая настройка модели'+ }+ },debug: {title: 'Тест модели',description: 'Отправьте реальный запрос к настроенной модели и проверьте ответ и время выполнения',diff --git a/frontend/src/i18n/locales/zh-CN.ts b/frontend/src/i18n/locales/zh-CN.tsindex b5142d82f..92ca1514c 100755--- a/frontend/src/i18n/locales/zh-CN.ts+++ b/frontend/src/i18n/locales/zh-CN.ts@@ -1978,6 +1978,29 @@ export default {copySuffix: ' 副本',builtinTag: '内置',confirmDelete: '确定删除模型「{name}」吗?',+ usage: {+ title: '模型无法删除',+ description: '模型「{name}」仍被以下配置引用。请先打开对应配置并更换模型,再重新删除。',+ knowledgeBases: '知识库({count})',+ agents: '智能体({count})',+ longTermMemory: '长期记忆',+ openConfiguration: '打开配置',+ truncated: '仅显示前 {shown} 个,共 {total} 个',+ bindings: {+ embedding_model: 'Embedding 模型',+ summary_model: '摘要模型',+ image_processing_model: '图片处理模型',+ vlm_model: '视觉理解模型',+ asr_model: '语音识别模型',+ wiki_synthesis_model: 'Wiki 综合模型',+ chat_model: '对话模型',+ rerank_model: '重排序模型',+ query_understand_model: '问题理解模型',+ follow_up_model: '追问模型',+ extract_model: '记忆提取模型',+ unknown: '其他模型配置'+ }+ },debug: {title: '模型测试',description: '向已配置的模型发送真实请求,查看响应与耗时',diff --git a/frontend/src/views/agent/AgentEditorModal.vue b/frontend/src/views/agent/AgentEditorModal.vueindex 7cee3807c..757f0b039 100644--- a/frontend/src/views/agent/AgentEditorModal.vue+++ b/frontend/src/views/agent/AgentEditorModal.vue@@ -3,6 +3,9 @@<Transition name="modal"><div v-if="visible" class="settings-overlay" @click.self="handleClose"><div class="settings-modal">+ <div v-if="editorInitializing" class="editor-initializing" role="status" :aria-label="$t('common.loading')">+ <t-loading size="medium" :text="$t('common.loading')" />+ </div><!-- 关闭按钮 --><button class="close-btn" @click="handleClose" :aria-label="$t('common.close')"><svg width="20" height="20" viewBox="0 0 20 20" fill="currentColor">@@ -1777,6 +1780,7 @@$t('common.cancel')}}</t-button><t-button v-if="!props.readOnly" theme="primary" data-guide="agent-create-submit" :loading="saving"+ :disabled="editorInitializing"@click="handleSave">{{saveButtonLabel}}</t-button>@@ -2014,6 +2018,7 @@ onBeforeUnmount(() => {})const saving = ref(false);+const editorInitializing = ref(false);const allModels = ref<ModelConfig[]>([]);const kbOptions = ref<{ label: string; value: string; type?: 'document' | 'faq'; count?: number; shared?: boolean; orgName?: string; ragEnabled?: boolean; wikiEnabled?: boolean; capabilities?: KBCapabilities }[]>([]);@@ -3358,13 +3363,19 @@ const needsRerankModel = computed(() => {return false;});+let editorInitializationGeneration = 0;+// 监听可见性变化,重置表单watch(() => props.visible, async (val) => {+ const generation = ++editorInitializationGeneration;if (val) {+ editorInitializing.value = true;+ try {savedAgent.value = null;currentSection.value = resolveEditorSection(props.initialSection);// 先加载依赖数据(包括默认配置)await loadDependencies();+ if (generation !== editorInitializationGeneration || !props.visible) return;if (props.mode === 'edit' && props.agent) {// 深度复制对象以避免引用问题@@ -3502,11 +3513,21 @@ watch(() => props.visible, async (val) => {}await syncInstalledSkills()+ if (generation !== editorInitializationGeneration || !props.visible) return;if (props.initialHighlightField) {await applyInitialFieldHighlight(props.initialHighlightField);+ if (generation !== editorInitializationGeneration || !props.visible) return;+ }+ } catch (error) {+ console.error('Failed to initialize agent editor', error);+ } finally {+ if (generation === editorInitializationGeneration && props.visible) {+ editorInitializing.value = false;+ }}} else {+ editorInitializing.value = false;clearFieldHighlight();agentIMChannelCount.value = 0;agentEmbedChannelCount.value = 0;@@ -4827,6 +4848,16 @@ const handleSave = async () => {overflow: hidden;}+.editor-initializing {+ position: absolute;+ inset: 0;+ z-index: 20;+ display: flex;+ align-items: center;+ justify-content: center;+ background: var(--td-bg-color-container);+}+.close-btn {position: absolute;top: 16px;diff --git a/frontend/src/views/agent/AgentList.vue b/frontend/src/views/agent/AgentList.vueindex 1fa5e1eef..9d5fe3cef 100644--- a/frontend/src/views/agent/AgentList.vue+++ b/frontend/src/views/agent/AgentList.vue@@ -812,7 +812,7 @@</template><script setup lang="ts">-import { computed, onMounted, onUnmounted, ref, watch } from 'vue'+import { computed, nextTick, onMounted, onUnmounted, ref, watch } from 'vue'import { useRoute, useRouter } from 'vue-router'import { MessagePlugin, Icon as TIcon } from 'tdesign-vue-next'import { deleteAgent, copyAgent, type CustomAgent } from '@/api/agent'@@ -828,7 +828,7 @@ import type { SharedAgentInfo, OrganizationSharedAgentItem } from '@/api/organizimport AgentEditorModal from './AgentEditorModal.vue'import ContextualGuide from '@/components/ContextualGuide.vue'import TenantModelsGuide from '@/components/TenantModelsGuide.vue'-import { markContextualGuideDone } from '@/config/contextualGuides'+import { focusAgentEditorSection, markContextualGuideDone } from '@/config/contextualGuides'import { useTenantModelReadiness } from '@/composables/useTenantModelReadiness'import { useUIStore } from '@/stores/ui'import AgentAvatar from '@/components/AgentAvatar.vue'@@ -1108,7 +1108,7 @@ const applyAgentListData = (res: { data: CustomAgent[]; disabled_own_agent_ids:showMore: false,disabled_by_me: disabledOwnIds.includes(agent.id)}))- checkAndOpenEditModal()+ void checkAndOpenEditModal()}const fetchList = (force = false) => {@@ -1118,7 +1118,7 @@ const fetchList = (force = false) => {orgStore.fetchOrganizations({ force }),orgStore.fetchSharedAgents({ force }),]).finally(() => { loading.value = false }).then(() => {- checkAndOpenEditModal()+ void checkAndOpenEditModal()// 各空间智能体数量已由 GET /organizations 的 resource_counts 带回,存于 orgStore.resourceCountsconst counts = orgStore.resourceCounts?.agents?.by_organizationif (counts) spaceAgentCountByOrg.value = { ...counts }@@ -1138,7 +1138,10 @@ const resolveAgentForEdit = (editId: string, sourceTenantId?: string): CustomAgereturn null}-const checkAndOpenEditModal = () => {+let editOpenGeneration = 0++const checkAndOpenEditModal = async () => {+ const generation = ++editOpenGenerationconst editId = route.query.edit as stringconst section = route.query.section as stringconst sourceTenantId = route.query.sourceTenantId as string | undefined@@ -1152,13 +1155,36 @@ const checkAndOpenEditModal = () => {}if (editId) {const agent = resolveAgentForEdit(editId, sourceTenantId)- if (agent) {+ // A route change can remove a creator filter before the corresponding+ // all-agent fetch completes. Keep the deep-link query intact so the list+ // refresh callback can resolve and open the target instead of losing it.+ if (!agent) return++ const requestedSection = section || 'basic'+ const requestedHighlight = (route.query.highlight as string) || ''+ if (+ editorVisible.value+ && editingAgent.value?.id === agent.id+ && !requestedHighlight+ ) {+ // Global Settings may be covering this exact editor. Preserve any+ // unsaved draft and focus the requested configuration section in place.+ editorInitialSection.value = requestedSection+ focusAgentEditorSection(requestedSection)+ } else {+ // A global Settings dialog can be opened on top of an existing agent+ // editor. Flush visible=false before loading the deep-linked target so+ // AgentEditorModal's visibility watcher rebuilds its form data.+ editorVisible.value = false+ await nextTick()+ if (generation !== editOpenGeneration) returneditingAgent.value = agenteditorMode.value = 'edit'- editorInitialSection.value = section || 'basic'- editorInitialHighlightField.value = (route.query.highlight as string) || ''+ editorInitialSection.value = requestedSection+ editorInitialHighlightField.value = requestedHighlighteditorVisible.value = true}+ if (generation !== editOpenGeneration) return// Drop the transient edit/section params but preserve other filter// state (scope / creator / q) so refreshing doesn't reset the view.const { edit: _e, section: _s, highlight: _h, sourceTenantId: _st, ...rest } = route.query@@ -1174,7 +1200,7 @@ watch(() => route.query.edit,(v) => {if (v && (agents.value.length > 0 || sharedAgents.value.length > 0)) {- checkAndOpenEditModal()+ void checkAndOpenEditModal()}},)diff --git a/frontend/src/views/knowledge/KnowledgeBaseEditorModal.vue b/frontend/src/views/knowledge/KnowledgeBaseEditorModal.vueindex 59e4b6fb8..363715d32 100644--- a/frontend/src/views/knowledge/KnowledgeBaseEditorModal.vue+++ b/frontend/src/views/knowledge/KnowledgeBaseEditorModal.vue@@ -3,6 +3,9 @@<Transition name="modal"><div v-if="visible" class="settings-overlay" @click.self="handleClose"><div class="settings-modal">+ <div v-if="loading" class="editor-initializing" role="status" :aria-label="$t('common.loading')">+ <t-loading size="medium" :text="$t('common.loading')" />+ </div><!-- 关闭按钮 --><button class="close-btn" @click="handleClose" :aria-label="$t('general.close')"><svg width="20" height="20" viewBox="0 0 20 20" fill="currentColor">@@ -445,7 +448,8 @@<t-button theme="default" variant="outline" @click="handleClose">{{ $t('common.cancel') }}</t-button>- <t-button theme="primary" data-guide="kb-create-submit" @click="handleSubmit" :loading="saving">+ <t-button theme="primary" data-guide="kb-create-submit" @click="handleSubmit" :loading="saving"+ :disabled="loading">{{ saveButtonLabel }}</t-button></div>@@ -815,8 +819,19 @@ const loadAllModels = async (force = false) => {}}+let kbEditorLoadGeneration = 0++const isCurrentKBLoad = (generation: number, kbId: string) => (+ generation === kbEditorLoadGeneration+ && props.visible+ && activeKbId.value === kbId+)+// 加载知识库数据(编辑模式)-const loadKBData = async (kbIdOverride?: string) => {+const loadKBData = async (+ kbIdOverride?: string,+ generation = kbEditorLoadGeneration,+) => {const kbId = kbIdOverride ?? activeKbId.valueif (editorMode.value !== 'edit' || !kbId) return@@ -826,6 +841,8 @@ const loadKBData = async (kbIdOverride?: string) => {getKnowledgeBaseById(kbId),listKnowledgeFiles(kbId, { page: 1, page_size: 1 })])++ if (!isCurrentKBLoad(generation, kbId)) returnif (!kbInfo || !kbInfo.data) {throw new Error(t('knowledgeEditor.messages.notFound'))@@ -940,11 +957,14 @@ const loadKBData = async (kbIdOverride?: string) => {initialStorageProvider.value = formData.value.storageProviderinitialIndexingStrategy.value = { ...formData.value.indexingStrategy }} catch (error) {+ if (!isCurrentKBLoad(generation, kbId)) returnconsole.error('Failed to load knowledge base data:', error)MessagePlugin.error(t('knowledgeEditor.messages.loadDataFailed'))handleClose()} finally {- loading.value = false+ if (isCurrentKBLoad(generation, kbId)) {+ loading.value = false+ }}}@@ -1530,15 +1550,19 @@ const resetState = () => {const handleClose = () => {emit('update:visible', false)setTimeout(() => {+ if (props.visible) returnresetState()}, 300)}// 监听弹窗打开/关闭watch(() => props.visible, async (newVal) => {+ const generation = ++kbEditorLoadGenerationif (newVal) {// 打开弹窗时,先重置状态resetState()+ loading.value = true+ const targetKbId = props.kbId// 检查是否有初始 section,如果有则跳转if (uiStore.kbEditorInitialSection) {@@ -1547,20 +1571,24 @@ watch(() => props.visible, async (newVal) => {// 加载模型列表与空间默认存储引擎(创建 KB 时即使用,不依赖是否打开「存储引擎」Tab)await Promise.all([loadAllModels(), loadTenantDefaultStorageProvider()])++ if (generation !== kbEditorLoadGeneration || !props.visible) return// 根据模式加载数据- if (props.mode === 'edit' && props.kbId) {- await loadKBData()+ if (props.mode === 'edit' && targetKbId) {+ await loadKBData(targetKbId, generation)} else {// 创建模式:初始化空表单,并预填空间默认存储引擎formData.value = initFormData(props.initialType || 'document')formData.value.storageProvider = tenantDefaultStorageProvider.valuehasFiles.value = falseapplyDefaultModelsIfEmpty()+ loading.value = false}} else {// 关闭弹窗时,延迟重置状态(等待动画结束)setTimeout(() => {+ if (props.visible) returnresetState()currentSection.value = 'basic' // 重置为默认 section}, 300)@@ -1608,6 +1636,16 @@ watch(overflow: hidden;}+.editor-initializing {+ position: absolute;+ inset: 0;+ z-index: 20;+ display: flex;+ align-items: center;+ justify-content: center;+ background: var(--td-bg-color-container);+}+.close-btn {position: absolute;top: 20px;diff --git a/frontend/src/views/settings/ModelSettings.vue b/frontend/src/views/settings/ModelSettings.vueindex ba50c641b..749c12425 100644--- a/frontend/src/views/settings/ModelSettings.vue+++ b/frontend/src/views/settings/ModelSettings.vue@@ -132,6 +132,124 @@</div></t-loading>+ <t-dialog+ v-model:visible="showUsageDialog"+ :header="$t('modelSettings.usage.title')"+ :footer="false"+ width="680px"+ destroy-on-close+ >+ <div v-if="usageConflict" class="model-usage-dialog">+ <p class="model-usage-dialog__description">+ {{ $t('modelSettings.usage.description', { name: usageConflictModelName }) }}+ </p>++ <div class="model-usage-dialog__content">+ <section v-if="usageConflict.knowledge_bases.length" class="model-usage-group">+ <h3>+ {{ $t('modelSettings.usage.knowledgeBases', {+ count: modelUsageResourceCount(usageConflict.knowledge_bases, usageConflict.knowledge_base_total)+ }) }}+ </h3>+ <ul>+ <li v-for="resource in usageConflict.knowledge_bases" :key="resource.id">+ <div class="model-usage-resource">+ <strong>{{ resource.name || resource.id }}</strong>+ <div class="model-usage-bindings">+ <t-tag+ v-for="(binding, index) in resource.bindings"+ :key="`${binding}-${index}`"+ size="small"+ variant="light"+ >+ {{ $t(modelUsageBindingI18nKey(binding)) }}+ </t-tag>+ </div>+ </div>+ <t-button+ theme="primary"+ variant="text"+ size="small"+ @click="openUsageResource('knowledge_base', resource.id, resource.bindings)"+ >+ {{ $t('modelSettings.usage.openConfiguration') }}+ </t-button>+ </li>+ </ul>+ <p+ v-if="modelUsageListTruncated(usageConflict.knowledge_bases, usageConflict.knowledge_base_total)"+ class="model-usage-truncated"+ >+ {{ $t('modelSettings.usage.truncated', {+ shown: usageConflict.knowledge_bases.length,+ total: modelUsageResourceCount(usageConflict.knowledge_bases, usageConflict.knowledge_base_total)+ }) }}+ </p>+ </section>++ <section v-if="usageConflict.agents.length" class="model-usage-group">+ <h3>{{ $t('modelSettings.usage.agents', {+ count: modelUsageResourceCount(usageConflict.agents, usageConflict.agent_total)+ }) }}</h3>+ <ul>+ <li v-for="resource in usageConflict.agents" :key="resource.id">+ <div class="model-usage-resource">+ <strong>{{ resource.name || resource.id }}</strong>+ <div class="model-usage-bindings">+ <t-tag+ v-for="(binding, index) in resource.bindings"+ :key="`${binding}-${index}`"+ size="small"+ variant="light"+ >+ {{ $t(modelUsageBindingI18nKey(binding)) }}+ </t-tag>+ </div>+ </div>+ <t-button+ theme="primary"+ variant="text"+ size="small"+ @click="openUsageResource('agent', resource.id, resource.bindings)"+ >+ {{ $t('modelSettings.usage.openConfiguration') }}+ </t-button>+ </li>+ </ul>+ <p+ v-if="modelUsageListTruncated(usageConflict.agents, usageConflict.agent_total)"+ class="model-usage-truncated"+ >+ {{ $t('modelSettings.usage.truncated', {+ shown: usageConflict.agents.length,+ total: modelUsageResourceCount(usageConflict.agents, usageConflict.agent_total)+ }) }}+ </p>+ </section>++ <section v-if="usageConflict.long_term_memory.bindings.length" class="model-usage-group">+ <h3>{{ $t('modelSettings.usage.longTermMemory') }}</h3>+ <div class="model-usage-memory">+ <div class="model-usage-bindings">+ <t-tag+ v-for="(binding, index) in usageConflict.long_term_memory.bindings"+ :key="`${binding}-${index}`"+ size="small"+ variant="light"+ >+ {{ $t(modelUsageBindingI18nKey(binding)) }}+ </t-tag>+ </div>+ </div>+ </section>+ </div>++ <div class="model-usage-dialog__actions">+ <t-button @click="showUsageDialog = false">{{ $t('common.close') }}</t-button>+ </div>+ </div>+ </t-dialog>+<!-- 模型编辑器抽屉 --><ModelEditorDialog v-model:visible="showDialog" :model-type="currentModelType" :model-data="editingModel"@confirm="handleModelSave" />@@ -141,30 +259,58 @@</template><script setup lang="ts">-import { ref, computed, onMounted, watch } from 'vue'+import { ref, computed, nextTick, onMounted, watch } from 'vue'import { MessagePlugin } from 'tdesign-vue-next'import { AddIcon, PlayCircleIcon } from 'tdesign-icons-vue-next'import { useI18n } from 'vue-i18n'+import { useRouter } from 'vue-router'import ModelEditorDialog from '@/components/ModelEditorDialog.vue'import ModelDebugDrawer from '@/components/ModelDebugDrawer.vue'-import { listModels, createModel, updateModel as updateModelAPI, deleteModel as deleteModelAPI, type ModelConfig } from '@/api/model'+import {+ listModels,+ createModel,+ updateModel as updateModelAPI,+ deleteModel as deleteModelAPI,+ ModelInUseError,+ modelUsageBindingI18nKey,+ modelUsageKnowledgeBaseSection,+ modelUsageListTruncated,+ modelUsageResourceCount,+ modelUsageResourceRoute,+ type ModelConfig,+ type ModelUsageDetails,+ type ModelUsageResourceKind,+} from '@/api/model'import { useAuthStore } from '@/stores/auth'import { useUIStore } from '@/stores/ui'+import { focusKbEditorSection } from '@/config/contextualGuides'const { t, te } = useI18n()const authStore = useAuthStore()const uiStore = useUIStore()+const router = useRouter()type ModelType = 'chat' | 'embedding' | 'rerank' | 'vllm' | 'asr'type FilterType = 'all' | ModelTypeconst showDialog = ref(false)const showDebugDrawer = ref(false)+const showUsageDialog = ref(false)+const usageConflict = ref<ModelUsageDetails | null>(null)+const usageConflictModelName = ref('')const currentModelType = ref<ModelType>('chat')const editingModel = ref<any>(null)const loading = ref(true)const activeTypeFilter = ref<FilterType>('all')const MODEL_TAB_TYPES: FilterType[] = ['chat', 'embedding', 'rerank', 'vllm', 'asr']+const KNOWLEDGE_BASE_EDITOR_HOST_ROUTES = new Set([+ 'home',+ 'knowledgeBaseList',+ 'knowledgeBaseDetail',+ 'globalCreatChat',+ 'kbCreatChat',+ 'chat',+])watch(() => uiStore.settingsInitialSubSection,(sub) => {@@ -508,10 +654,56 @@ const deleteModel = async (_type: ModelType, modelId: string) => {await loadModels()} catch (error: any) {console.error('删除模型失败:', error)+ if (error instanceof ModelInUseError) {+ usageConflict.value = error.details+ usageConflictModelName.value = model?.display_name || model?.name || modelId+ showUsageDialog.value = true+ return+ }MessagePlugin.error(error.message || t('modelSettings.toasts.deleteFailed'))}}+const openUsageResource = async (+ kind: ModelUsageResourceKind,+ id: string,+ bindings: readonly string[] = [],+) => {+ showUsageDialog.value = false+ const knowledgeBaseSection = modelUsageKnowledgeBaseSection(bindings)+ // The UI store can outlive the route component that owns the KB editor.+ // Only focus an existing editor when the current route still mounts one;+ // otherwise a stale visible/id pair would make a direct Settings page no-op.+ const routeName = router.currentRoute.value.name+ const canFocusExistingKnowledgeBase = kind === 'knowledge_base'+ && uiStore.showKBEditorModal+ && uiStore.currentKBId === id+ && typeof routeName === 'string'+ && KNOWLEDGE_BASE_EDITOR_HOST_ROUTES.has(routeName)++ uiStore.closeSettings()+ await nextTick()++ if (canFocusExistingKnowledgeBase) {+ // Keep unsaved edits when the referenced KB is already open underneath+ // global Settings; only move the existing editor to the relevant section.+ focusKbEditorSection(knowledgeBaseSection)+ return+ }++ if (kind === 'knowledge_base') {+ uiStore.closeKBEditor()+ await nextTick()+ }+ // Both the KB editor and global Settings can already be open underneath the+ // usage dialog. Flush their false state before reusing either component so+ // its visible watcher reloads the target object instead of keeping stale data.+ await router.push(modelUsageResourceRoute(kind, id, bindings))+ if (kind === 'knowledge_base') {+ uiStore.openKBSettings(id, knowledgeBaseSection)+ }+}+// 获取模型操作菜单选项const getModelOptions = (type: ModelType, model: any) => {const options: any[] = []@@ -986,4 +1178,88 @@ onMounted(() => {margin-bottom: 16px;}}++.model-usage-dialog__description {+ margin: 0 0 16px;+ color: var(--td-text-color-secondary);+ line-height: 1.6;+}++.model-usage-dialog__content {+ max-height: min(58vh, 560px);+ overflow-y: auto;+ padding-right: 4px;+}++.model-usage-group {+ & + & {+ margin-top: 20px;+ }++ h3 {+ margin: 0 0 8px;+ font-size: 14px;+ font-weight: 600;+ color: var(--td-text-color-primary);+ }++ ul {+ margin: 0;+ padding: 0;+ list-style: none;+ border: 1px solid var(--td-component-stroke);+ border-radius: 8px;+ overflow: hidden;+ }++ li {+ display: flex;+ align-items: center;+ justify-content: space-between;+ gap: 12px;+ padding: 10px 12px;++ & + li {+ border-top: 1px solid var(--td-component-stroke);+ }+ }+}++.model-usage-truncated {+ margin: 8px 0 0;+ font-size: 12px;+ color: var(--td-text-color-secondary);+ line-height: 1.5;+}++.model-usage-resource {+ min-width: 0;++ strong {+ display: block;+ margin-bottom: 6px;+ overflow: hidden;+ color: var(--td-text-color-primary);+ text-overflow: ellipsis;+ white-space: nowrap;+ }+}++.model-usage-bindings {+ display: flex;+ flex-wrap: wrap;+ gap: 6px;+}++.model-usage-memory {+ padding: 10px 12px;+ border: 1px solid var(--td-component-stroke);+ border-radius: 8px;+}++.model-usage-dialog__actions {+ display: flex;+ justify-content: flex-end;+ margin-top: 20px;+}</style>diff --git a/frontend/src/views/settings/modelUsageDetails.test.ts b/frontend/src/views/settings/modelUsageDetails.test.tsnew file mode 100644index 000000000..48f4f4b2a--- /dev/null+++ b/frontend/src/views/settings/modelUsageDetails.test.ts@@ -0,0 +1,44 @@+import assert from 'node:assert/strict'+import { readFileSync } from 'node:fs'+import test from 'node:test'++const source = readFileSync(new URL('./ModelSettings.vue', import.meta.url), 'utf8')+const agentListSource = readFileSync(new URL('../agent/AgentList.vue', import.meta.url), 'utf8')+const knowledgeBaseEditorSource = readFileSync(+ new URL('../knowledge/KnowledgeBaseEditorModal.vue', import.meta.url),+ 'utf8',+)+const agentEditorSource = readFileSync(new URL('../agent/AgentEditorModal.vue', import.meta.url), 'utf8')++test('model deletion renders structured usage groups and localized fallback errors', () => {+ assert.match(source, /error instanceof ModelInUseError/)+ assert.match(source, /usageConflict\.knowledge_bases/)+ assert.match(source, /usageConflict\.agents/)+ assert.match(source, /usageConflict\.long_term_memory\.bindings/)+ assert.match(source, /MessagePlugin\.error\(error\.message \|\| t\('modelSettings\.toasts\.deleteFailed'\)\)/)+})++test('referenced knowledge bases and agents open their relevant configuration pages', () => {+ assert.match(source, /openUsageResource\('knowledge_base', resource\.id, resource\.bindings\)/)+ assert.match(source, /openUsageResource\('agent', resource\.id, resource\.bindings\)/)+ assert.match(source, /uiStore\.closeKBEditor\(\)/)+ assert.match(source, /uiStore\.closeSettings\(\)/)+ assert.match(source, /await nextTick\(\)/)+ assert.match(+ source,+ /const routeName = router\.currentRoute\.value\.name[\s\S]*canFocusExistingKnowledgeBase[\s\S]*KNOWLEDGE_BASE_EDITOR_HOST_ROUTES\.has\(routeName\)[\s\S]*focusKbEditorSection\(knowledgeBaseSection\)/,+ )+ assert.match(source, /await router\.push\(modelUsageResourceRoute\(kind, id, bindings\)\)/)+ assert.match(source, /uiStore\.openKBSettings\(id, knowledgeBaseSection\)/)+ assert.match(+ agentListSource,+ /editingAgent\.value\?\.id === agent\.id[\s\S]*focusAgentEditorSection\(requestedSection\)[\s\S]*editorVisible\.value = false\s*await nextTick\(\)\s*if \(generation !== editOpenGeneration\) return[\s\S]*editorVisible\.value = true/,+ )+ assert.match(agentListSource, /const agent = resolveAgentForEdit\([\s\S]*if \(!agent\) return[\s\S]*router\.replace/)+ assert.match(agentEditorSource, /v-if="editorInitializing"[\s\S]*:disabled="editorInitializing"/)+ assert.match(agentEditorSource, /generation !== editorInitializationGeneration \|\| !props\.visible/)+ assert.match(knowledgeBaseEditorSource, /v-if="loading"[\s\S]*:disabled="loading"/)+ assert.match(knowledgeBaseEditorSource, /isCurrentKBLoad\(generation, kbId\)/)+ assert.match(knowledgeBaseEditorSource, /generation !== kbEditorLoadGeneration \|\| !props\.visible/)+ assert.match(knowledgeBaseEditorSource, /setTimeout\(\(\) => \{\s*if \(props\.visible\) return\s*resetState\(\)/)+})diff --git a/internal/application/repository/custom_agent.go b/internal/application/repository/custom_agent.goindex eab35e727..a62e85214 100644--- a/internal/application/repository/custom_agent.go+++ b/internal/application/repository/custom_agent.go@@ -74,6 +74,36 @@ func (r *customAgentRepository) CountByModelID(return count, err}+// ListModelUsages returns active agents that reference modelID. Only id, name,+// and config are loaded; the config is decoded locally and never returned.+func (r *customAgentRepository) ListModelUsages(+ ctx context.Context, tenantID uint64, modelID string,+) ([]types.ModelUsageResource, error) {+ rows := make([]*types.CustomAgent, 0)+ query := r.db.WithContext(ctx).+ Model(&types.CustomAgent{}).+ Select("id", "name", "config").+ Where("tenant_id = ?", tenantID)+ query = scopeCustomAgentsByModelID(query, modelID)+ if err := query.Order("name ASC, id ASC").Limit(types.ModelUsageListLimit).Find(&rows).Error; err != nil {+ return nil, err+ }++ usages := make([]types.ModelUsageResource, 0, len(rows))+ for _, row := range rows {+ bindings := customAgentModelUsageBindings(row, modelID)+ if len(bindings) == 0 {+ continue+ }+ usages = append(usages, types.ModelUsageResource{+ ID: row.ID,+ Name: row.Name,+ Bindings: bindings,+ })+ }+ return usages, nil+}+// CountBySandboxConfigID counts agents pointing at a sandbox config.//// Used only to warn the admin which agents reference a config; never use it todiff --git a/internal/application/repository/knowledgebase.go b/internal/application/repository/knowledgebase.goindex b19517298..b3f279679 100644--- a/internal/application/repository/knowledgebase.go+++ b/internal/application/repository/knowledgebase.go@@ -217,3 +217,37 @@ func (r *knowledgeBaseRepository) CountByModelID(err := query.Count(&count).Errorreturn count, err}++// ListModelUsages returns active knowledge bases that reference modelID. It+// selects only the columns needed to identify the resource and its bindings;+// GORM's default scope excludes soft-deleted rows.+func (r *knowledgeBaseRepository) ListModelUsages(+ ctx context.Context, tenantID uint64, modelID string,+) ([]types.ModelUsageResource, error) {+ rows := make([]*types.KnowledgeBase, 0)+ query := r.db.WithContext(ctx).+ Model(&types.KnowledgeBase{}).+ Select(+ "id", "name", "embedding_model_id", "summary_model_id",+ "image_processing_config", "vlm_config", "asr_config", "wiki_config",+ ).+ Where("tenant_id = ?", tenantID)+ query = scopeKnowledgeBasesByModelID(query, modelID)+ if err := query.Order("name ASC, id ASC").Limit(types.ModelUsageListLimit).Find(&rows).Error; err != nil {+ return nil, err+ }++ usages := make([]types.ModelUsageResource, 0, len(rows))+ for _, row := range rows {+ bindings := knowledgeBaseModelUsageBindings(row, modelID)+ if len(bindings) == 0 {+ continue+ }+ usages = append(usages, types.ModelUsageResource{+ ID: row.ID,+ Name: row.Name,+ Bindings: bindings,+ })+ }+ return usages, nil+}diff --git a/internal/application/repository/model_usage.go b/internal/application/repository/model_usage.goindex 686b271ef..1e522ecf8 100644--- a/internal/application/repository/model_usage.go+++ b/internal/application/repository/model_usage.go@@ -1,9 +1,57 @@package repositoryimport (+ "github.com/Tencent/WeKnora/internal/types""gorm.io/gorm")+func knowledgeBaseModelUsageBindings(kb *types.KnowledgeBase, modelID string) []types.ModelUsageBinding {+ bindings := make([]types.ModelUsageBinding, 0, 6)+ if kb.EmbeddingModelID == modelID {+ bindings = append(bindings, types.ModelUsageBindingEmbeddingModel)+ }+ if kb.SummaryModelID == modelID {+ bindings = append(bindings, types.ModelUsageBindingSummaryModel)+ }+ if kb.ImageProcessingConfig.ModelID == modelID {+ bindings = append(bindings, types.ModelUsageBindingImageProcessingModel)+ }+ if kb.VLMConfig.ModelID == modelID {+ bindings = append(bindings, types.ModelUsageBindingVLMModel)+ }+ if kb.ASRConfig.ModelID == modelID {+ bindings = append(bindings, types.ModelUsageBindingASRModel)+ }+ if kb.WikiConfig != nil && kb.WikiConfig.SynthesisModelID == modelID {+ bindings = append(bindings, types.ModelUsageBindingWikiSynthesisModel)+ }+ return bindings+}++func customAgentModelUsageBindings(agent *types.CustomAgent, modelID string) []types.ModelUsageBinding {+ bindings := make([]types.ModelUsageBinding, 0, 6)+ if agent.Config.ModelID == modelID {+ bindings = append(bindings, types.ModelUsageBindingChatModel)+ }+ if agent.Config.RerankModelID == modelID {+ bindings = append(bindings, types.ModelUsageBindingRerankModel)+ }+ if agent.Config.VLMModelID == modelID {+ bindings = append(bindings, types.ModelUsageBindingVLMModel)+ }+ if agent.Config.ASRModelID == modelID {+ bindings = append(bindings, types.ModelUsageBindingASRModel)+ }+ if agent.Config.QueryUnderstandModelID == modelID {+ bindings = append(bindings, types.ModelUsageBindingQueryUnderstandModel)+ }+ if agent.Config.QuestionSuggestions != nil &&+ agent.Config.QuestionSuggestions.FollowUps.ModelID == modelID {+ bindings = append(bindings, types.ModelUsageBindingFollowUpModel)+ }+ return bindings+}+// scopeKnowledgeBasesByModelID filters knowledge_bases rows that reference// modelID in any model-binding field.func scopeKnowledgeBasesByModelID(db *gorm.DB, modelID string) *gorm.DB {diff --git a/internal/application/repository/model_usage_test.go b/internal/application/repository/model_usage_test.goindex f8777a170..8698a17ad 100644--- a/internal/application/repository/model_usage_test.go+++ b/internal/application/repository/model_usage_test.go@@ -2,6 +2,7 @@ package repositoryimport ("context"+ "fmt""testing""github.com/Tencent/WeKnora/internal/types"@@ -68,6 +69,78 @@ func TestCountByModelID_KnowledgeBase(t *testing.T) {assert.Equal(t, int64(1), count)}+func TestListModelUsages_KnowledgeBase(t *testing.T) {+ ctx := context.Background()+ db := setupModelUsageTestDB(t)+ repo := NewKnowledgeBaseRepository(db)+ modelID := "all-kb-bindings"++ allBindings := makeKB(nil)+ allBindings.Name = "Zulu KB"+ allBindings.EmbeddingModelID = modelID+ allBindings.SummaryModelID = modelID+ allBindings.ImageProcessingConfig = types.ImageProcessingConfig{ModelID: modelID}+ allBindings.VLMConfig = types.VLMConfig{Enabled: true, ModelID: modelID}+ allBindings.ASRConfig = types.ASRConfig{Enabled: true, ModelID: modelID}+ allBindings.WikiConfig = &types.WikiConfig{SynthesisModelID: modelID}+ require.NoError(t, db.Create(allBindings).Error)++ vlmOnly := makeKB(nil)+ vlmOnly.Name = "Alpha KB"+ vlmOnly.VLMConfig = types.VLMConfig{Enabled: true, ModelID: modelID}+ require.NoError(t, db.Create(vlmOnly).Error)++ otherTenant := makeKB(nil)+ otherTenant.Name = "Other tenant"+ otherTenant.TenantID = 2+ otherTenant.EmbeddingModelID = modelID+ require.NoError(t, db.Create(otherTenant).Error)++ deleted := makeKB(nil)+ deleted.Name = "Deleted KB"+ deleted.EmbeddingModelID = modelID+ require.NoError(t, db.Create(deleted).Error)+ require.NoError(t, db.Delete(deleted).Error)++ usages, err := repo.ListModelUsages(ctx, 1, modelID)+ require.NoError(t, err)+ require.Len(t, usages, 2)+ assert.Equal(t, "Alpha KB", usages[0].Name)+ assert.Equal(t, []types.ModelUsageBinding{types.ModelUsageBindingVLMModel}, usages[0].Bindings)+ assert.Equal(t, "Zulu KB", usages[1].Name)+ assert.Equal(t, []types.ModelUsageBinding{+ types.ModelUsageBindingEmbeddingModel,+ types.ModelUsageBindingSummaryModel,+ types.ModelUsageBindingImageProcessingModel,+ types.ModelUsageBindingVLMModel,+ types.ModelUsageBindingASRModel,+ types.ModelUsageBindingWikiSynthesisModel,+ }, usages[1].Bindings)+}++func TestListModelUsages_KnowledgeBaseRespectsLimit(t *testing.T) {+ ctx := context.Background()+ db := setupModelUsageTestDB(t)+ repo := NewKnowledgeBaseRepository(db)+ modelID := "shared-embed"++ for i := 0; i < types.ModelUsageListLimit+3; i++ {+ kb := makeKB(nil)+ kb.Name = fmt.Sprintf("KB %03d", i)+ kb.EmbeddingModelID = modelID+ require.NoError(t, db.Create(kb).Error)+ }++ usages, err := repo.ListModelUsages(ctx, 1, modelID)+ require.NoError(t, err)+ require.Len(t, usages, types.ModelUsageListLimit)+ assert.Equal(t, "KB 000", usages[0].Name)++ count, err := repo.CountByModelID(ctx, 1, modelID)+ require.NoError(t, err)+ assert.Equal(t, int64(types.ModelUsageListLimit+3), count)+}+func TestCountByModelID_CustomAgent(t *testing.T) {ctx := context.Background()db := setupModelUsageTestDB(t)@@ -112,6 +185,66 @@ func TestCountByModelID_CustomAgent(t *testing.T) {assert.Equal(t, int64(1), count)}+func TestListModelUsages_CustomAgent(t *testing.T) {+ ctx := context.Background()+ db := setupModelUsageTestDB(t)+ repo := NewCustomAgentRepository(db)+ modelID := "all-agent-bindings"++ allBindings := &types.CustomAgent{+ ID: uuid.New().String(),+ Name: "Zulu agent",+ TenantID: 1,+ Config: types.CustomAgentConfig{+ ModelID: modelID,+ RerankModelID: modelID,+ VLMModelID: modelID,+ ASRModelID: modelID,+ QueryUnderstandModelID: modelID,+ QuestionSuggestions: &types.QuestionSuggestionConfig{+ FollowUps: types.FollowUpSuggestionConfig{ModelID: modelID},+ },+ },+ }+ require.NoError(t, repo.CreateAgent(ctx, allBindings))++ vlmOnly := &types.CustomAgent{+ ID: uuid.New().String(),+ Name: "Alpha agent",+ TenantID: 1,+ Config: types.CustomAgentConfig{VLMModelID: modelID},+ }+ require.NoError(t, repo.CreateAgent(ctx, vlmOnly))++ otherTenant := &types.CustomAgent{+ ID: uuid.New().String(), Name: "Other tenant", TenantID: 2,+ Config: types.CustomAgentConfig{ModelID: modelID},+ }+ require.NoError(t, repo.CreateAgent(ctx, otherTenant))++ deleted := &types.CustomAgent{+ ID: uuid.New().String(), Name: "Deleted agent", TenantID: 1,+ Config: types.CustomAgentConfig{ModelID: modelID},+ }+ require.NoError(t, repo.CreateAgent(ctx, deleted))+ require.NoError(t, repo.DeleteAgent(ctx, deleted.ID, deleted.TenantID))++ usages, err := repo.ListModelUsages(ctx, 1, modelID)+ require.NoError(t, err)+ require.Len(t, usages, 2)+ assert.Equal(t, "Alpha agent", usages[0].Name)+ assert.Equal(t, []types.ModelUsageBinding{types.ModelUsageBindingVLMModel}, usages[0].Bindings)+ assert.Equal(t, "Zulu agent", usages[1].Name)+ assert.Equal(t, []types.ModelUsageBinding{+ types.ModelUsageBindingChatModel,+ types.ModelUsageBindingRerankModel,+ types.ModelUsageBindingVLMModel,+ types.ModelUsageBindingASRModel,+ types.ModelUsageBindingQueryUnderstandModel,+ types.ModelUsageBindingFollowUpModel,+ }, usages[1].Bindings)+}+func TestCustomAgentSandboxConfigReferences(t *testing.T) {ctx := context.Background()db := setupModelUsageTestDB(t)diff --git a/internal/application/service/knowledgebase_pr3_test.go b/internal/application/service/knowledgebase_pr3_test.goindex 5b75bbbfc..d24616f7b 100644--- a/internal/application/service/knowledgebase_pr3_test.go+++ b/internal/application/service/knowledgebase_pr3_test.go@@ -125,9 +125,15 @@ func (r *fakeKBRepo) CountByVectorStoreID(_ context.Context, _ *gorm.DB, _ uint6func (r *fakeKBRepo) CountByModelID(_ context.Context, _ uint64, _ string) (int64, error) {return 0, nil}++func (r *fakeKBRepo) ListModelUsages(_ context.Context, _ uint64, _ string) ([]types.ModelUsageResource, error) {+ return []types.ModelUsageResource{}, nil+}+func (r *fakeKBRepo) SetUserKBPin(_ context.Context, _ uint64, _ string, _ string, _ bool) (*time.Time, error) {return nil, nil}+func (r *fakeKBRepo) ListUserKBPinIDs(_ context.Context, _ uint64, _ string) (map[string]time.Time, error) {return map[string]time.Time{}, nil}diff --git a/internal/application/service/model.go b/internal/application/service/model.goindex f213f28c1..f7f4696ad 100644--- a/internal/application/service/model.go+++ b/internal/application/service/model.go@@ -375,44 +375,28 @@ func (s *modelService) DeleteModel(ctx context.Context, id string) error {return apperrors.NewBadRequestError("builtin models cannot be deleted")}- kbCount, err := s.kbRepo.CountByModelID(ctx, tenantID, id)+ usage, err := s.getModelUsageDetails(ctx, tenantID, id)if err != nil {logger.ErrorWithFields(ctx, err, map[string]interface{}{"model_id": id,})return err}- agentCount, err := s.agentRepo.CountByModelID(ctx, tenantID, id)- if err != nil {- logger.ErrorWithFields(ctx, err, map[string]interface{}{- "model_id": id,- })- return err- }- if kbCount > 0 || agentCount > 0 {- logger.Warnf(ctx, "Model %s is in use: kb=%d agent=%d", id, kbCount, agentCount)- return apperrors.NewBadRequestError(formatModelInUseMessage(kbCount, agentCount, false))- }-- if s.tenantService != nil {- tenant, err := s.tenantService.GetTenantByID(ctx, tenantID)- if err != nil {- logger.ErrorWithFields(ctx, err, map[string]interface{}{- "model_id": id,- "tenant_id": tenantID,- })- return err+ if usage.InUse() {+ kbCount := usage.KnowledgeBaseTotal+ if kbCount == 0 {+ kbCount = int64(len(usage.KnowledgeBases))}- // Both models memory pins have to be checked. Deleting the extraction- // model leaves the workspace pointing at a model that no longer exists,- // and distillation only warns when it cannot resolve one, so auto- // extraction would stop with nothing surfaced to the admin who did it.- if tenant != nil && tenant.MemoryConfig != nil &&- (strings.TrimSpace(tenant.MemoryConfig.EmbeddingModelID) == id ||- strings.TrimSpace(tenant.MemoryConfig.ExtractModelID) == id) {- logger.Warnf(ctx, "Model %s is used by long-term memory", id)- return apperrors.NewBadRequestError(formatModelInUseMessage(0, 0, true))+ agentCount := usage.AgentTotal+ if agentCount == 0 {+ agentCount = int64(len(usage.Agents))}+ memoryInUse := len(usage.LongTermMemory.Bindings) > 0+ logger.Warnf(ctx, "Model %s is in use: kb=%d agent=%d memory=%t", id, kbCount, agentCount, memoryInUse)+ return apperrors.NewModelInUseError(+ formatModelInUseMessage(kbCount, agentCount, memoryInUse),+ usage,+ )}// Delete model from repository@@ -429,6 +413,73 @@ func (s *modelService) DeleteModel(ctx context.Context, id string) error {return nil}+func (s *modelService) getModelUsageDetails(+ ctx context.Context, tenantID uint64, modelID string,+) (types.ModelUsageDetails, error) {+ details := types.ModelUsageDetails{+ KnowledgeBases: make([]types.ModelUsageResource, 0),+ Agents: make([]types.ModelUsageResource, 0),+ LongTermMemory: types.ModelUsageMemory{Bindings: make([]types.ModelUsageBinding, 0)},+ }++ kbCount, err := s.kbRepo.CountByModelID(ctx, tenantID, modelID)+ if err != nil {+ return details, err+ }+ details.KnowledgeBaseTotal = kbCount+ if kbCount > 0 {+ details.KnowledgeBases, err = s.kbRepo.ListModelUsages(ctx, tenantID, modelID)+ if err != nil {+ return details, err+ }+ if details.KnowledgeBases == nil {+ details.KnowledgeBases = make([]types.ModelUsageResource, 0)+ }+ }++ agentCount, err := s.agentRepo.CountByModelID(ctx, tenantID, modelID)+ if err != nil {+ return details, err+ }+ details.AgentTotal = agentCount+ if agentCount > 0 {+ details.Agents, err = s.agentRepo.ListModelUsages(ctx, tenantID, modelID)+ if err != nil {+ return details, err+ }+ if details.Agents == nil {+ details.Agents = make([]types.ModelUsageResource, 0)+ }+ }++ if s.tenantService == nil {+ return details, nil+ }+ tenant, err := s.tenantService.GetTenantByID(ctx, tenantID)+ if err != nil {+ return details, err+ }+ if tenant == nil || tenant.MemoryConfig == nil {+ return details, nil+ }++ // Both memory model pins have to be checked. Deleting either one leaves+ // the workspace pointing at a model that no longer exists.+ if strings.TrimSpace(tenant.MemoryConfig.EmbeddingModelID) == modelID {+ details.LongTermMemory.Bindings = append(+ details.LongTermMemory.Bindings,+ types.ModelUsageBindingEmbeddingModel,+ )+ }+ if strings.TrimSpace(tenant.MemoryConfig.ExtractModelID) == modelID {+ details.LongTermMemory.Bindings = append(+ details.LongTermMemory.Bindings,+ types.ModelUsageBindingExtractModel,+ )+ }+ return details, nil+}+// GetEmbeddingModel retrieves and initializes an embedding model instance// Takes a model ID and returns an Embedder interface implementationfunc (s *modelService) GetEmbeddingModel(ctx context.Context, modelId string) (embedding.Embedder, error) {diff --git a/internal/application/service/model_delete_test.go b/internal/application/service/model_delete_test.goindex a41acb328..187c45e31 100644--- a/internal/application/service/model_delete_test.go+++ b/internal/application/service/model_delete_test.go@@ -2,6 +2,7 @@ package serviceimport ("context"+ "errors""testing""time"@@ -13,7 +14,9 @@ import ()type stubKBRepoForModelDelete struct {- count int64+ usages []types.ModelUsageResource+ count *int64+ usageErr error}func (s *stubKBRepoForModelDelete) CreateKnowledgeBase(context.Context, *types.KnowledgeBase) error {@@ -42,7 +45,16 @@ func (s *stubKBRepoForModelDelete) CountByVectorStoreID(context.Context, *gorm.Dreturn 0, nil}func (s *stubKBRepoForModelDelete) CountByModelID(context.Context, uint64, string) (int64, error) {- return s.count, nil+ if s.count != nil {+ return *s.count, s.usageErr+ }+ return int64(len(s.usages)), s.usageErr+}++func (s *stubKBRepoForModelDelete) ListModelUsages(+ context.Context, uint64, string,+) ([]types.ModelUsageResource, error) {+ return s.usages, s.usageErr}func (s *stubKBRepoForModelDelete) SetUserKBPin(context.Context, uint64, string, string, bool) (*time.Time, error) {return nil, nil@@ -52,7 +64,9 @@ func (s *stubKBRepoForModelDelete) ListUserKBPinIDs(context.Context, uint64, str}type stubAgentRepoForModelDelete struct {- count int64+ usages []types.ModelUsageResource+ count *int64+ usageErr error}func (s *stubAgentRepoForModelDelete) CreateAgent(context.Context, *types.CustomAgent) error {@@ -69,7 +83,16 @@ func (s *stubAgentRepoForModelDelete) UpdateAgent(context.Context, *types.Custom}func (s *stubAgentRepoForModelDelete) DeleteAgent(context.Context, string, uint64) error { return nil }func (s *stubAgentRepoForModelDelete) CountByModelID(context.Context, uint64, string) (int64, error) {- return s.count, nil+ if s.count != nil {+ return *s.count, s.usageErr+ }+ return int64(len(s.usages)), s.usageErr+}++func (s *stubAgentRepoForModelDelete) ListModelUsages(+ context.Context, uint64, string,+) ([]types.ModelUsageResource, error) {+ return s.usages, s.usageErr}func (s *stubAgentRepoForModelDelete) CountBySandboxConfigID(context.Context, uint64, string) (int64, error) {return 0, nil@@ -116,8 +139,11 @@ func TestDeleteModel_RejectsWhenReferenced(t *testing.T) {svc := NewModelService(&stubModelRepoForDelete{model: &types.Model{ID: modelID, TenantID: 1}},- &stubKBRepoForModelDelete{count: 1},- &stubAgentRepoForModelDelete{count: 0},+ &stubKBRepoForModelDelete{usages: []types.ModelUsageResource{+ {ID: "kb-1", Name: "Product docs", Bindings: []types.ModelUsageBinding{types.ModelUsageBindingVLMModel}},+ {ID: "kb-2", Name: "Engineering", Bindings: []types.ModelUsageBinding{types.ModelUsageBindingVLMModel}},+ }},+ &stubAgentRepoForModelDelete{},nil, nil, nil,)@@ -125,8 +151,16 @@ func TestDeleteModel_RejectsWhenReferenced(t *testing.T) {require.Error(t, err)appErr, ok := apperrors.IsAppError(err)require.True(t, ok)- assert.Equal(t, apperrors.ErrBadRequest, appErr.Code)- assert.Contains(t, appErr.Message, "knowledge base")+ assert.Equal(t, apperrors.ErrModelInUse, appErr.Code)+ assert.Contains(t, appErr.Message, "2 knowledge base(s)")+ details, ok := appErr.Details.(types.ModelUsageDetails)+ require.True(t, ok)+ require.Len(t, details.KnowledgeBases, 2)+ assert.Equal(t, int64(2), details.KnowledgeBaseTotal)+ assert.Equal(t, "Product docs", details.KnowledgeBases[0].Name)+ assert.Equal(t, []types.ModelUsageBinding{types.ModelUsageBindingVLMModel}, details.KnowledgeBases[0].Bindings)+ assert.Equal(t, "Engineering", details.KnowledgeBases[1].Name)+ assert.Equal(t, []types.ModelUsageBinding{types.ModelUsageBindingVLMModel}, details.KnowledgeBases[1].Bindings)}func TestDeleteModel_RejectsWhenUsedByAgent(t *testing.T) {@@ -135,8 +169,11 @@ func TestDeleteModel_RejectsWhenUsedByAgent(t *testing.T) {svc := NewModelService(&stubModelRepoForDelete{model: &types.Model{ID: modelID, TenantID: 1}},- &stubKBRepoForModelDelete{count: 0},- &stubAgentRepoForModelDelete{count: 2},+ &stubKBRepoForModelDelete{},+ &stubAgentRepoForModelDelete{usages: []types.ModelUsageResource{+ {ID: "agent-1", Name: "Support", Bindings: []types.ModelUsageBinding{types.ModelUsageBindingChatModel}},+ {ID: "agent-2", Name: "Writer", Bindings: []types.ModelUsageBinding{types.ModelUsageBindingFollowUpModel}},+ }},nil, nil, nil,)@@ -144,7 +181,12 @@ func TestDeleteModel_RejectsWhenUsedByAgent(t *testing.T) {require.Error(t, err)appErr, ok := apperrors.IsAppError(err)require.True(t, ok)+ assert.Equal(t, apperrors.ErrModelInUse, appErr.Code)assert.Contains(t, appErr.Message, "2 agent(s)")+ details, ok := appErr.Details.(types.ModelUsageDetails)+ require.True(t, ok)+ assert.Len(t, details.Agents, 2)+ assert.Equal(t, int64(2), details.AgentTotal)}func TestDeleteModel_SucceedsWhenUnreferenced(t *testing.T) {@@ -170,6 +212,85 @@ func TestDeleteModel_SucceedsWhenUnreferenced(t *testing.T) {assert.True(t, deleted)}+func TestGetModelUsageDetails_NormalizesEmptyCollections(t *testing.T) {+ svc := NewModelService(+ &stubModelRepoForDelete{},+ &stubKBRepoForModelDelete{},+ &stubAgentRepoForModelDelete{},+ nil, nil, nil,+ )++ details, err := svc.(*modelService).getModelUsageDetails(context.Background(), 1, "unused-model")+ require.NoError(t, err)+ assert.NotNil(t, details.KnowledgeBases)+ assert.NotNil(t, details.Agents)+ assert.NotNil(t, details.LongTermMemory.Bindings)+ assert.Equal(t, int64(0), details.KnowledgeBaseTotal)+ assert.Equal(t, int64(0), details.AgentTotal)+}++func TestDeleteModel_DoesNotDeleteWhenUsageLookupFails(t *testing.T) {+ ctx := context.WithValue(context.Background(), types.TenantIDContextKey, uint64(1))+ modelID := "lookup-failure"+ wantErr := errors.New("usage lookup failed")+ deleted := false++ svc := NewModelService(+ &stubModelRepoForDelete{+ model: &types.Model{ID: modelID, TenantID: 1},+ delete: func(string) error {+ deleted = true+ return nil+ },+ },+ &stubKBRepoForModelDelete{usageErr: wantErr},+ &stubAgentRepoForModelDelete{},+ nil, nil, nil,+ )++ err := svc.DeleteModel(ctx, modelID)+ require.ErrorIs(t, err, wantErr)+ assert.False(t, deleted)+}++func TestDeleteModel_ReportsUntruncatedTotalsWhenListsAreCapped(t *testing.T) {+ ctx := context.WithValue(context.Background(), types.TenantIDContextKey, uint64(1))+ modelID := "popular-embedding"+ kbTotal := int64(80)+ agentTotal := int64(12)++ svc := NewModelService(+ &stubModelRepoForDelete{model: &types.Model{ID: modelID, TenantID: 1}},+ &stubKBRepoForModelDelete{+ count: &kbTotal,+ usages: []types.ModelUsageResource{+ {ID: "kb-1", Name: "Alpha", Bindings: []types.ModelUsageBinding{types.ModelUsageBindingEmbeddingModel}},+ {ID: "kb-2", Name: "Beta", Bindings: []types.ModelUsageBinding{types.ModelUsageBindingEmbeddingModel}},+ },+ },+ &stubAgentRepoForModelDelete{+ count: &agentTotal,+ usages: []types.ModelUsageResource{+ {ID: "agent-1", Name: "Support", Bindings: []types.ModelUsageBinding{types.ModelUsageBindingChatModel}},+ },+ },+ nil, nil, nil,+ )++ err := svc.DeleteModel(ctx, modelID)+ require.Error(t, err)+ appErr, ok := apperrors.IsAppError(err)+ require.True(t, ok)+ assert.Contains(t, appErr.Message, "80 knowledge base(s)")+ assert.Contains(t, appErr.Message, "12 agent(s)")+ details, ok := appErr.Details.(types.ModelUsageDetails)+ require.True(t, ok)+ assert.Equal(t, int64(80), details.KnowledgeBaseTotal)+ assert.Len(t, details.KnowledgeBases, 2)+ assert.Equal(t, int64(12), details.AgentTotal)+ assert.Len(t, details.Agents, 1)+}+type stubTenantServiceForModelDelete struct {tenant *types.Tenant}@@ -227,7 +348,11 @@ func TestDeleteModel_RejectsWhenUsedByMemory(t *testing.T) {require.Error(t, err)appErr, ok := apperrors.IsAppError(err)require.True(t, ok)+ assert.Equal(t, apperrors.ErrModelInUse, appErr.Code)assert.Contains(t, appErr.Message, "long-term memory")+ details, ok := appErr.Details.(types.ModelUsageDetails)+ require.True(t, ok)+ assert.Equal(t, []types.ModelUsageBinding{types.ModelUsageBindingEmbeddingModel}, details.LongTermMemory.Bindings)}// The extraction model is pinned by the workspace exactly like the embedding@@ -257,7 +382,42 @@ func TestDeleteModel_RejectsWhenUsedByMemoryExtraction(t *testing.T) {require.Error(t, err)appErr, ok := apperrors.IsAppError(err)require.True(t, ok)+ assert.Equal(t, apperrors.ErrModelInUse, appErr.Code)assert.Contains(t, appErr.Message, "long-term memory")+ details, ok := appErr.Details.(types.ModelUsageDetails)+ require.True(t, ok)+ assert.Equal(t, []types.ModelUsageBinding{types.ModelUsageBindingExtractModel}, details.LongTermMemory.Bindings)+}++func TestDeleteModel_ReportsAllMemoryBindings(t *testing.T) {+ ctx := context.WithValue(context.Background(), types.TenantIDContextKey, uint64(1))+ modelID := "shared-memory-model"++ svc := NewModelService(+ &stubModelRepoForDelete{model: &types.Model{ID: modelID, TenantID: 1}},+ &stubKBRepoForModelDelete{},+ &stubAgentRepoForModelDelete{},+ nil, nil,+ &stubTenantServiceForModelDelete{+ tenant: &types.Tenant{+ ID: 1,+ MemoryConfig: &types.MemoryConfig{+ Enabled: true, EmbeddingModelID: modelID, ExtractModelID: modelID,+ },+ },+ },+ )++ err := svc.DeleteModel(ctx, modelID)+ require.Error(t, err)+ appErr, ok := apperrors.IsAppError(err)+ require.True(t, ok)+ details, ok := appErr.Details.(types.ModelUsageDetails)+ require.True(t, ok)+ assert.Equal(t, []types.ModelUsageBinding{+ types.ModelUsageBindingEmbeddingModel,+ types.ModelUsageBindingExtractModel,+ }, details.LongTermMemory.Bindings)}func TestFormatModelInUseMessage(t *testing.T) {diff --git a/internal/application/service/vectorstore_test.go b/internal/application/service/vectorstore_test.goindex 7a9fd2c1e..8b6969ef2 100644--- a/internal/application/service/vectorstore_test.go+++ b/internal/application/service/vectorstore_test.go@@ -926,6 +926,9 @@ func (r *realKBRepo) CountByVectorStoreID(ctx context.Context, db *gorm.DB, tenafunc (r *realKBRepo) CountByModelID(_ context.Context, _ uint64, _ string) (int64, error) {return 0, nil}+func (r *realKBRepo) ListModelUsages(_ context.Context, _ uint64, _ string) ([]types.ModelUsageResource, error) {+ return []types.ModelUsageResource{}, nil+}// The remaining methods are not called by the tested code paths; declare them// so realKBRepo satisfies interfaces.KnowledgeBaseRepository.diff --git a/internal/errors/errors.go b/internal/errors/errors.goindex 98c9c20a5..43779a56b 100644--- a/internal/errors/errors.go+++ b/internal/errors/errors.go@@ -44,6 +44,11 @@ const (ErrVectorStoreBindingInvalid ErrorCode = 2200ErrVectorStoreUnavailable ErrorCode = 2201+ // Model lifecycle errors (2300-2399).+ // The dedicated code lets clients render structured usage details without+ // parsing the backwards-compatible English error message.+ ErrModelInUse ErrorCode = 2300+// Add more error codes here)@@ -75,6 +80,17 @@ func NewBadRequestError(message string) *AppError {}}+// NewModelInUseError creates the typed HTTP 400 returned when active tenant+// resources still reference a model.+func NewModelInUseError(message string, details any) *AppError {+ return &AppError{+ Code: ErrModelInUse,+ Message: message,+ Details: details,+ HTTPCode: http.StatusBadRequest,+ }+}+// NewUnauthorizedError creates an unauthorized errorfunc NewUnauthorizedError(message string) *AppError {return &AppError{diff --git a/internal/handler/model.go b/internal/handler/model.goindex 0aa297719..df50b7a34 100644--- a/internal/handler/model.go+++ b/internal/handler/model.go@@ -667,6 +667,7 @@ func (h *ModelHandler) UpdateModel(c *gin.Context) {// @Produce json// @Param id path string true "模型ID"// @Success 200 {object} map[string]interface{} "删除成功"+// @Failure 400 {object} errors.AppError "模型仍被知识库、智能体或长期记忆引用"// @Failure 404 {object} errors.AppError "模型不存在"// @Security Bearer// @Security ApiKeyAuthdiff --git a/internal/middleware/error_handler_model_usage_test.go b/internal/middleware/error_handler_model_usage_test.gonew file mode 100644index 000000000..0d57045a5--- /dev/null+++ b/internal/middleware/error_handler_model_usage_test.go@@ -0,0 +1,70 @@+package middleware++import (+ "encoding/json"+ "net/http"+ "net/http/httptest"+ "testing"++ apperrors "github.com/Tencent/WeKnora/internal/errors"+ "github.com/Tencent/WeKnora/internal/types"+ "github.com/gin-gonic/gin"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+)++func TestErrorHandler_PreservesStructuredModelUsageDetails(t *testing.T) {+ gin.SetMode(gin.TestMode)+ router := gin.New()+ router.Use(ErrorHandler())+ router.DELETE("/models/:id", func(c *gin.Context) {+ _ = c.Error(apperrors.NewModelInUseError(+ "model is used by 2 knowledge base(s); reconfigure or remove those references before deleting",+ types.ModelUsageDetails{+ KnowledgeBases: []types.ModelUsageResource{+ {+ ID: "kb-1",+ Name: "Product docs",+ Bindings: []types.ModelUsageBinding{types.ModelUsageBindingVLMModel},+ },+ {+ ID: "kb-2",+ Name: "Engineering",+ Bindings: []types.ModelUsageBinding{+ types.ModelUsageBindingEmbeddingModel,+ types.ModelUsageBindingSummaryModel,+ },+ },+ },+ Agents: []types.ModelUsageResource{},+ LongTermMemory: types.ModelUsageMemory{Bindings: []types.ModelUsageBinding{}},+ },+ ))+ })++ request := httptest.NewRequest(http.MethodDelete, "/models/model-1", nil)+ response := httptest.NewRecorder()+ router.ServeHTTP(response, request)++ require.Equal(t, http.StatusBadRequest, response.Code)+ var body struct {+ Success bool `json:"success"`+ Error struct {+ Code apperrors.ErrorCode `json:"code"`+ Message string `json:"message"`+ Details types.ModelUsageDetails `json:"details"`+ } `json:"error"`+ }+ require.NoError(t, json.Unmarshal(response.Body.Bytes(), &body))+ assert.False(t, body.Success)+ assert.Equal(t, apperrors.ErrModelInUse, body.Error.Code)+ assert.NotEmpty(t, body.Error.Message)+ require.Len(t, body.Error.Details.KnowledgeBases, 2)+ assert.Equal(t, "Product docs", body.Error.Details.KnowledgeBases[0].Name)+ assert.Equal(t,+ []types.ModelUsageBinding{types.ModelUsageBindingEmbeddingModel, types.ModelUsageBindingSummaryModel},+ body.Error.Details.KnowledgeBases[1].Bindings,+ )+ assert.Empty(t, body.Error.Details.Agents)+ assert.Empty(t, body.Error.Details.LongTermMemory.Bindings)+}diff --git a/internal/router/router_api_key_capabilities_test.go b/internal/router/router_api_key_capabilities_test.goindex 2289264cb..6fa54a4b5 100644--- a/internal/router/router_api_key_capabilities_test.go+++ b/internal/router/router_api_key_capabilities_test.go@@ -360,6 +360,7 @@ func TestTenantInfrastructureRoutesDeclareSpecificCapabilities(t *testing.T) {}{{http.MethodGet, "/api/v1/tenants", types.APIKeyCapabilityManageTenantSettings},{http.MethodGet, "/api/v1/models", types.APIKeyCapabilityManageModels},+ {http.MethodDelete, "/api/v1/models/:id", types.APIKeyCapabilityManageModels},{http.MethodPost, "/api/v1/evaluation", types.APIKeyCapabilityRunEvaluations},{http.MethodGet, "/api/v1/system/info", types.APIKeyCapabilityManageVectorStores},{http.MethodGet, "/api/v1/mcp-services", types.APIKeyCapabilityManageMCPServices},diff --git a/internal/types/interfaces/custom_agent.go b/internal/types/interfaces/custom_agent.goindex 28a4b2c17..e96e2e80d 100644--- a/internal/types/interfaces/custom_agent.go+++ b/internal/types/interfaces/custom_agent.go@@ -136,6 +136,11 @@ type CustomAgentRepository interface {// CountByModelID counts active agents in the tenant whose config references// the given model ID (chat, rerank, VLM, ASR, query-understand, etc.).CountByModelID(ctx context.Context, tenantID uint64, modelID string) (int64, error)+ // ListModelUsages returns the minimal active agent projections that+ // reference the model, with every matching binding merged per object.+ // Implementations must cap the result at types.ModelUsageListLimit;+ // callers that need the untruncated size should use CountByModelID.+ ListModelUsages(ctx context.Context, tenantID uint64, modelID string) ([]types.ModelUsageResource, error)// CountBySandboxConfigID counts agents pointing at a sandbox config.//diff --git a/internal/types/interfaces/knowledgebase.go b/internal/types/interfaces/knowledgebase.goindex 20e9fe377..e8c17bdd8 100644--- a/internal/types/interfaces/knowledgebase.go+++ b/internal/types/interfaces/knowledgebase.go@@ -225,6 +225,11 @@ type KnowledgeBaseRepository interface {// CountByModelID counts active KBs in the tenant that reference the given// model ID in any model-binding field (embedding, summary, VLM, ASR, etc.).CountByModelID(ctx context.Context, tenantID uint64, modelID string) (int64, error)+ // ListModelUsages returns the minimal active KB projections that reference+ // the model, with every matching binding merged per object. Implementations+ // must cap the result at types.ModelUsageListLimit; callers that need the+ // untruncated size should use CountByModelID.+ ListModelUsages(ctx context.Context, tenantID uint64, modelID string) ([]types.ModelUsageResource, error)// SetUserKBPin inserts or removes a row in user_kb_pins for the given// (tenant, user, kb) triple. Returns the resulting pinned_at (nil when// pinned=false) and an error. The tenant_id is captured to supportdiff --git a/internal/types/model.go b/internal/types/model.goindex 176060439..14f26ad4e 100644--- a/internal/types/model.go+++ b/internal/types/model.go@@ -31,6 +31,63 @@ const (ModelStatusDownloadFailed ModelStatus = "download_failed" // Model download failed)+// ModelUsageBinding is a stable API identifier for one configuration field+// that references a model. Clients localize these values; repository column+// names and JSON paths must not leak into the response contract.+type ModelUsageBinding string++// Model usage binding constants identify supported model-reference roles.+const (+ ModelUsageBindingEmbeddingModel ModelUsageBinding = "embedding_model"+ ModelUsageBindingSummaryModel ModelUsageBinding = "summary_model"+ ModelUsageBindingImageProcessingModel ModelUsageBinding = "image_processing_model"+ ModelUsageBindingVLMModel ModelUsageBinding = "vlm_model"+ ModelUsageBindingASRModel ModelUsageBinding = "asr_model"+ ModelUsageBindingWikiSynthesisModel ModelUsageBinding = "wiki_synthesis_model"+ ModelUsageBindingChatModel ModelUsageBinding = "chat_model"+ ModelUsageBindingRerankModel ModelUsageBinding = "rerank_model"+ ModelUsageBindingQueryUnderstandModel ModelUsageBinding = "query_understand_model"+ ModelUsageBindingFollowUpModel ModelUsageBinding = "follow_up_model"+ ModelUsageBindingExtractModel ModelUsageBinding = "extract_model"+)++// ModelUsageResource is the minimal, non-sensitive projection returned when a+// knowledge base or agent prevents model deletion.+type ModelUsageResource struct {+ ID string `json:"id"`+ Name string `json:"name"`+ Bindings []ModelUsageBinding `json:"bindings"`+}++// ModelUsageMemory describes workspace-level long-term-memory model pins.+type ModelUsageMemory struct {+ Bindings []ModelUsageBinding `json:"bindings"`+}++// ModelUsageListLimit caps how many knowledge bases or agents are listed in a+// model-in-use error. Totals are returned separately so the cap cannot+// under-count the references that actually block deletion.+const ModelUsageListLimit = 50++// ModelUsageDetails explains every active tenant-scoped reference that blocks+// model deletion. KnowledgeBases and Agents may be truncated to+// ModelUsageListLimit entries; KnowledgeBaseTotal and AgentTotal are the+// untruncated counts used by the deletion guard and UI headings.+type ModelUsageDetails struct {+ KnowledgeBases []ModelUsageResource `json:"knowledge_bases"`+ Agents []ModelUsageResource `json:"agents"`+ LongTermMemory ModelUsageMemory `json:"long_term_memory"`+ KnowledgeBaseTotal int64 `json:"knowledge_base_total"`+ AgentTotal int64 `json:"agent_total"`+}++// InUse reports whether at least one active object references the model.+func (d ModelUsageDetails) InUse() bool {+ return d.KnowledgeBaseTotal > 0 || d.AgentTotal > 0 ||+ len(d.KnowledgeBases) > 0 || len(d.Agents) > 0 ||+ len(d.LongTermMemory.Bindings) > 0+}+// ModelSource represents the source of the modeltype ModelSource stringdiff --git a/website-docs/03-features/16-observability.md b/website-docs/03-features/16-observability.mdindex 230089a11..15e97b620 100644--- a/website-docs/03-features/16-observability.md+++ b/website-docs/03-features/16-observability.md@@ -251,7 +251,7 @@ r.GET("/health", func(c *gin.Context) {- `scopeKnowledgeBasesByModelID`:匹配 `knowledge_bases` 中任一模型绑定字段 —— `embedding_model_id`、`summary_model_id`、`image_processing_config.model_id`、`vlm_config.model_id`、`asr_config.model_id`、`wiki_config.synthesis_model_id`(Postgres 用 `->>` JSON 操作符,SQLite 用 `json_extract`,双方言等价)。- `scopeCustomAgentsByModelID`:匹配 `custom_agents.config` 中的 `model_id`、`rerank_model_id`、`vlm_model_id`、`asr_model_id`、`query_understand_model_id`、`question_suggestions.follow_ups.model_id`。-- 消费方:`knowledgebase.go` / `custom_agent.go` 仓储的 `CountByModelID`,被 `internal/application/service/model.go` 的删除守卫调用(KB 或 Agent 引用计数 > 0 时阻止删除模型)。+- 消费方:`knowledgebase.go` / `custom_agent.go` 仓储的 `ListModelUsages` 复用上述 scope,返回租户内活动对象的最小投影(`id`、`name`、合并后的 `bindings`),条数上限为 `ModelUsageListLimit`(50)。`internal/application/service/model.go` 的删除守卫以 `CountByModelID` 得到的 `knowledge_base_total` / `agent_total` 为是否拦截的依据,并在 HTTP 400 的 `error.details` 中同时返回截断列表和总数。token 级别的模型用量则由 Langfuse Generation 的 `usage_details`(`TokenUsage`:input/output/total/cache_*)上报,在 Langfuse UI 中按模型 / 用户(`tenant:<id>`)/ 会话聚合查看。diff --git a/website-docs/04-api/02-api-model-system.md b/website-docs/04-api/02-api-model-system.mdindex af4bfdfd8..2e7714451 100644--- a/website-docs/04-api/02-api-model-system.md+++ b/website-docs/04-api/02-api-model-system.md@@ -85,6 +85,30 @@ curl -X PUT $BASE/api/v1/models/m-1 -H "Authorization: Bearer $TOKEN" \响应:200 `{"success":true,"message":"Model deleted"}`+仍被当前空间的知识库、智能体或长期记忆引用时,响应为 HTTP 400;兼容 message 保留,同时 `error.code=2300`,`error.details` 给出具体对象和引用位置:++```json+{+ "success": false,+ "error": {+ "code": 2300,+ "message": "model is used by 2 knowledge base(s); reconfigure or remove those references before deleting",+ "details": {+ "knowledge_bases": [+ {"id": "kb-1", "name": "Product docs", "bindings": ["vlm_model"]},+ {"id": "kb-2", "name": "Engineering", "bindings": ["vlm_model"]}+ ],+ "agents": [],+ "long_term_memory": {"bindings": []},+ "knowledge_base_total": 2,+ "agent_total": 0+ }+ }+}+```++知识库绑定值:`embedding_model`、`summary_model`、`image_processing_model`、`vlm_model`、`asr_model`、`wiki_synthesis_model`;智能体绑定值:`chat_model`、`rerank_model`、`vlm_model`、`asr_model`、`query_understand_model`、`follow_up_model`;长期记忆绑定值:`embedding_model`、`extract_model`。详情包含对象 `id`、`name`、合并后的 `bindings`,以及 `knowledge_base_total` / `agent_total`。列表最多各 50 条,删除守卫以总数为准。+```bashcurl -X DELETE $BASE/api/v1/models/m-1 -H "Authorization: Bearer $TOKEN"```