From 9896aebfb5741a6cbdd2fb34522014a9d595a073 Mon Sep 17 00:00:00 2001
From: Soulter <905617992@qq.com>
Date: Mon, 5 Jan 2026 20:20:09 +0800
Subject: [PATCH] feat: enhance provider source configuration with custom hints
 and tooltips

---
 .../provider/ProviderModelsPanel.vue          | 43 +++++++++++++------
 .../src/composables/useProviderSources.ts     | 19 ++++++++
 .../i18n/locales/en-US/features/provider.json | 11 ++++-
 .../i18n/locales/zh-CN/features/provider.json | 11 ++++-
 dashboard/src/views/ProviderPage.vue          |  7 +--
 5 files changed, 72 insertions(+), 19 deletions(-)

diff --git a/dashboard/src/components/provider/ProviderModelsPanel.vue b/dashboard/src/components/provider/ProviderModelsPanel.vue
index a27e63fdf..fa81a3da1 100644
--- a/dashboard/src/components/provider/ProviderModelsPanel.vue
+++ b/dashboard/src/components/provider/ProviderModelsPanel.vue
@@ -44,14 +44,16 @@
     >
       <template v-if="entries.length > 0">
         <template v-for="entry in entries" :key="entry.type === 'configured' ? `provider-${entry.provider.id}` : `model-${entry.model}`">
-          <v-list-item
-            v-if="entry.type === 'configured'"
-            class="provider-compact-item"
-            @click="emit('open-provider-edit', entry.provider)"
-          >
-            <v-list-item-title class="font-weight-medium text-truncate">
-              {{ entry.provider.id }}
-            </v-list-item-title>
+          <v-tooltip location="top" max-width="400" v-if="entry.type === 'configured'">
+            <template #activator="{ props }">
+              <v-list-item
+                v-bind="props"
+                class="provider-compact-item"
+                @click="emit('open-provider-edit', entry.provider)"
+              >
+                <v-list-item-title class="font-weight-medium text-truncate">
+                  {{ entry.provider.id }}
+                </v-list-item-title>
             <v-list-item-subtitle class="text-caption text-grey d-flex align-center ga-1" style="font-family: monospace;">
               <span>{{ entry.provider.model }}</span>
               <v-icon v-if="supportsImageInput(entry.metadata)" size="14" color="grey">
@@ -109,10 +111,18 @@
                 <v-btn icon="mdi-delete" size="small" variant="text" color="error" @click.stop="emit('delete-provider', entry.provider)"></v-btn>
               </div>
             </template>
-          </v-list-item>
+              </v-list-item>
+            </template>
+            <div>
+              <div><strong>{{ tm('models.tooltips.providerId') }}:</strong> {{ entry.provider.id }}</div>
+              <div><strong>{{ tm('models.tooltips.modelId') }}:</strong> {{ entry.provider.model }}</div>
+            </div>
+          </v-tooltip>
 
-          <v-list-item v-else class="cursor-pointer" @click="emit('add-model-provider', entry.model)">
-            <v-list-item-title>{{ entry.model }}</v-list-item-title>
+          <v-tooltip location="top" max-width="400" v-else>
+            <template #activator="{ props }">
+              <v-list-item v-bind="props" class="cursor-pointer" @click="emit('add-model-provider', entry.model)">
+                <v-list-item-title>{{ entry.model }}</v-list-item-title>
             <v-list-item-subtitle class="text-caption text-grey d-flex align-center ga-1">
               <span>{{ entry.model }}</span>
               <v-icon v-if="supportsImageInput(entry.metadata)" size="14" color="grey">
@@ -128,10 +138,15 @@
                 {{ formatContextLimit(entry.metadata) }}
               </span>
             </v-list-item-subtitle>
-            <template #append>
-              <v-btn icon="mdi-plus" size="small" variant="text" color="primary"></v-btn>
+                <template #append>
+                  <v-btn icon="mdi-plus" size="small" variant="text" color="primary"></v-btn>
+                </template>
+              </v-list-item>
             </template>
-          </v-list-item>
+            <div>
+              <div><strong>{{ tm('models.tooltips.modelId') }}:</strong> {{ entry.model }}</div>
+            </div>
+          </v-tooltip>
         </template>
       </template>
       <template v-else>
diff --git a/dashboard/src/composables/useProviderSources.ts b/dashboard/src/composables/useProviderSources.ts
index dc0059b04..514c372c7 100644
--- a/dashboard/src/composables/useProviderSources.ts
+++ b/dashboard/src/composables/useProviderSources.ts
@@ -241,6 +241,24 @@ export function useProviderSources(options: UseProviderSourcesOptions) {
     return providers.value.filter((provider: any) => getProviderType(provider) === selectedProviderType.value)
   })
 
+  const providerSourceSchema = computed(() => {
+    if (!configSchema.value || !configSchema.value.provider) {
+      return configSchema.value
+    }
+
+    // 创建一个深拷贝以避免修改原始 schema
+    const customSchema = JSON.parse(JSON.stringify(configSchema.value))
+
+    // 为 provider source 的 id 字段添加自定义 hint
+    if (customSchema.provider?.items?.id) {
+      customSchema.provider.items.id.hint = tm('providerSources.hints.id')
+      customSchema.provider.items.key.hint = tm('providerSources.hints.key')
+      customSchema.provider.items.api_base.hint = tm('providerSources.hints.apiBase')
+    }
+
+    return customSchema
+  })
+
   // ===== Watches =====
   watch(editableProviderSource, () => {
     if (suppressSourceWatch) return
@@ -646,6 +664,7 @@ export function useProviderSources(options: UseProviderSourcesOptions) {
     basicSourceConfig,
     advancedSourceConfig,
     manualProviderId,
+    providerSourceSchema,
 
     // helpers
     resolveSourceIcon,
diff --git a/dashboard/src/i18n/locales/en-US/features/provider.json b/dashboard/src/i18n/locales/en-US/features/provider.json
index 5f4a7987c..8d80d0b0b 100644
--- a/dashboard/src/i18n/locales/en-US/features/provider.json
+++ b/dashboard/src/i18n/locales/en-US/features/provider.json
@@ -108,6 +108,11 @@
       "name": "Name",
       "apiKey": "API Key",
       "baseUrl": "Base URL"
+    },
+    "hints": {
+      "id": "Provider source ID (not provider ID)",
+      "key": "API key for authentication",
+      "apiBase": "Custom API endpoint URL"
     }
   },
   "models": {
@@ -130,6 +135,10 @@
     "manualDialogPreviewHint": "Generated as sourceId/modelId",
     "manualModelRequired": "Please enter a model ID",
     "manualModelExists": "Model already exists",
-    "configure": "Configure"
+    "configure": "Configure",
+    "tooltips": {
+      "providerId": "Provider ID",
+      "modelId": "Model ID"
+    }
   }
 } 
\ No newline at end of file
diff --git a/dashboard/src/i18n/locales/zh-CN/features/provider.json b/dashboard/src/i18n/locales/zh-CN/features/provider.json
index 84b9d6c58..10d8edc7c 100644
--- a/dashboard/src/i18n/locales/zh-CN/features/provider.json
+++ b/dashboard/src/i18n/locales/zh-CN/features/provider.json
@@ -109,6 +109,11 @@
       "name": "名称",
       "apiKey": "API Key",
       "baseUrl": "Base URL"
+    },
+    "hints": {
+      "id": "提供商源唯一 ID（不是提供商 ID）",
+      "key": "API 密钥",
+      "apiBase": "自定义 API 端点 URL"
     }
   },
   "models": {
@@ -131,6 +136,10 @@
     "manualDialogPreviewHint": "生成规则：源ID/模型ID",
     "manualModelRequired": "请输入模型 ID",
     "manualModelExists": "该模型已存在",
-    "configure": "配置"
+    "configure": "配置",
+    "tooltips": {
+      "providerId": "提供商 ID",
+      "modelId": "模型 ID"
+    }
   }
 } 
\ No newline at end of file
diff --git a/dashboard/src/views/ProviderPage.vue b/dashboard/src/views/ProviderPage.vue
index 8d7e83578..e9b6edd78 100644
--- a/dashboard/src/views/ProviderPage.vue
+++ b/dashboard/src/views/ProviderPage.vue
@@ -67,7 +67,7 @@
                 <v-card-text>
                   <template v-if="selectedProviderSource">
                     <div>
-                      <AstrBotConfig v-if="basicSourceConfig" :iterable="basicSourceConfig" :metadata="configSchema"
+                      <AstrBotConfig v-if="basicSourceConfig" :iterable="basicSourceConfig" :metadata="providerSourceSchema"
                         metadataKey="provider" :is-editing="true" />
                     </div>
 
@@ -78,7 +78,7 @@
                         </v-expansion-panel-title>
                         <v-expansion-panel-text>
                           <AstrBotConfig v-if="advancedSourceConfig" :iterable="advancedSourceConfig"
-                            :metadata="configSchema" metadataKey="provider" :is-editing="true" />
+                            :metadata="providerSourceSchema" metadataKey="provider" :is-editing="true" />
                         </v-expansion-panel-text>
                       </v-expansion-panel>
                     </v-expansion-panels>
@@ -208,7 +208,7 @@
     <v-dialog v-model="showProviderEditDialog" width="800">
       <v-card :title="providerEditData?.id || tm('dialogs.config.editTitle')">
         <v-card-text class="py-4">
-          <small style="color: gray;">不建议修改 ID，可能会导致指向该模型的相关配置（如默认模型、插件相关配置等）失效。</small>
+          <small style="color: gray;">不建议修改 ID，可能会导致指向该模型的相关配置（如默认模型、插件相关配置等）失效。旧版本 AstrBot 的 “提供商 ID” 是下方的 “ID”。</small>
           <AstrBotConfig v-if="providerEditData" :iterable="providerEditData" :metadata="configSchema"
             metadataKey="provider" :is-editing="true" />
         </v-card-text>
@@ -299,6 +299,7 @@ const {
   testingProviders,
   isSourceModified,
   configSchema,
+  providerSourceSchema,
   manualModelId,
   modelSearch,
   providerTypes,