From 6cb1e6581118853ae98f087a022553945178e299 Mon Sep 17 00:00:00 2001
From: Zhicheng Han <zhicheng.han@mathematik.uni-goettingen.de>
Date: Sun, 10 May 2026 18:51:22 +0200
Subject: [PATCH 1/4] feat(models): add WUI model display aliases

Persist display-only model aliases in Web UI app config, surface them in the model selector/search, and keep canonical model IDs for Hermes calls.
---
 packages/client/src/api/hermes/system.ts      |  17 ++-
 .../src/components/layout/ModelSelector.vue   |  72 +++++++++-
 packages/client/src/i18n/locales/en.ts        |   6 +
 packages/client/src/i18n/locales/zh.ts        |   6 +
 packages/client/src/stores/hermes/app.ts      |  36 ++++-
 .../server/src/controllers/hermes/models.ts   | 131 +++++++++++++++++-
 packages/server/src/routes/hermes/models.ts   |   1 +
 packages/server/src/services/app-config.ts    |   4 +
 tests/client/app-store.test.ts                |  44 ++++++
 tests/server/model-alias-controller.test.ts   | 130 +++++++++++++++++
 10 files changed, 434 insertions(+), 13 deletions(-)
 create mode 100644 tests/server/model-alias-controller.test.ts

diff --git a/packages/client/src/api/hermes/system.ts b/packages/client/src/api/hermes/system.ts
index c3589511..67fe702c 100644
--- a/packages/client/src/api/hermes/system.ts
+++ b/packages/client/src/api/hermes/system.ts
@@ -32,8 +32,8 @@ export interface AvailableModelGroup {
   models: string[]
   api_key: string
   builtin?: boolean
-  /** 可选：模型 ID -> 元数据（preview/disabled）。目前仅 Copilot 提供。 */
-  model_meta?: Record<string, { preview?: boolean; disabled?: boolean }>
+  /** 可选：模型 ID -> 元数据（preview/disabled/alias）。alias 仅用于 Web UI 展示。 */
+  model_meta?: Record<string, { preview?: boolean; disabled?: boolean; alias?: string }>
 }
 
 export interface AvailableModelsResponse {
@@ -41,6 +41,8 @@ export interface AvailableModelsResponse {
   default_provider: string
   groups: AvailableModelGroup[]
   allProviders: AvailableModelGroup[]
+  /** Web UI-only display aliases keyed by provider -> canonical model ID. */
+  model_aliases?: Record<string, Record<string, string>>
 }
 
 export interface CustomProvider {
@@ -80,6 +82,17 @@ export async function updateDefaultModel(data: {
   })
 }
 
+export async function updateModelAlias(data: {
+  provider: string
+  model: string
+  alias: string
+}): Promise<void> {
+  await request('/api/hermes/model-alias', {
+    method: 'PUT',
+    body: JSON.stringify(data),
+  })
+}
+
 export async function addCustomProvider(data: CustomProvider): Promise<void> {
   await request('/api/hermes/config/providers', {
     method: 'POST',
diff --git a/packages/client/src/components/layout/ModelSelector.vue b/packages/client/src/components/layout/ModelSelector.vue
index 45c60d0f..cf0bdeb4 100644
--- a/packages/client/src/components/layout/ModelSelector.vue
+++ b/packages/client/src/components/layout/ModelSelector.vue
@@ -1,17 +1,24 @@
 <script setup lang="ts">
 import { ref, computed } from 'vue'
-import { NModal, NInput, NSelect } from 'naive-ui'
+import { NButton, NModal, NInput, NSelect, useMessage } from 'naive-ui'
 import { useAppStore } from '@/stores/hermes/app'
 import { useI18n } from 'vue-i18n'
 
 const { t } = useI18n()
 const appStore = useAppStore()
+const message = useMessage()
 
 const showModal = ref(false)
 const searchQuery = ref('')
 const collapsedGroups = ref<Record<string, boolean>>({})
 const customInput = ref('')
 const customProvider = ref('')
+const showAliasModal = ref(false)
+const aliasProvider = ref('')
+const aliasModel = ref('')
+const aliasInput = ref('')
+
+const selectedDisplayName = computed(() => appStore.displayModelName(appStore.selectedModel, appStore.selectedProvider))
 
 const providerOptions = computed(() => {
   const current = appStore.selectedProvider
@@ -43,7 +50,10 @@ const filteredGroups = computed(() => {
   return modelGroupsWithCustom.value
     .map(g => ({
       ...g,
-      models: g.models.filter(m => m.toLowerCase().includes(q)),
+      models: g.models.filter(m => {
+        const displayName = appStore.displayModelName(m, g.provider)
+        return m.toLowerCase().includes(q) || displayName.toLowerCase().includes(q)
+      }),
     }))
     .filter(g => g.models.length > 0 || g.label.toLowerCase().includes(q))
 })
@@ -64,6 +74,32 @@ function handleSelect(model: string, provider: string) {
   searchQuery.value = ''
 }
 
+function modelDisplayName(model: string, provider: string) {
+  return appStore.displayModelName(model, provider)
+}
+
+function modelAlias(model: string, provider: string) {
+  return appStore.getModelAlias(model, provider)
+}
+
+function openAliasEditor(model: string, provider: string) {
+  aliasModel.value = model
+  aliasProvider.value = provider
+  aliasInput.value = appStore.getModelAlias(model, provider)
+  showAliasModal.value = true
+}
+
+async function saveAlias() {
+  if (!aliasModel.value || !aliasProvider.value) return
+  try {
+    await appStore.setModelAlias(aliasModel.value, aliasProvider.value, aliasInput.value)
+    showAliasModal.value = false
+  } catch (err) {
+    console.error('Failed to save model alias:', err)
+    message.error(t('models.aliasSaveFailed'))
+  }
+}
+
 function handleCustomSubmit() {
   const model = customInput.value.trim()
   if (!model || !customProvider.value) return
@@ -89,7 +125,7 @@ function openModal() {
   <div class="model-selector">
     <div class="model-label">{{ t('models.title') }}</div>
     <button class="model-trigger" @click="openModal">
-      <span class="model-name" :title="appStore.selectedModel">{{ appStore.selectedModel || '—' }}</span>
+      <span class="model-name" :title="appStore.selectedModel">{{ selectedDisplayName || '—' }}</span>
       <svg class="model-arrow" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
         <polyline points="6 9 12 15 18 9" />
       </svg>
@@ -134,10 +170,16 @@ function openModal() {
               :title="group.model_meta?.[model]?.disabled ? t('models.disabledTooltip') : ''"
               @click="handleSelect(model, group.provider)"
             >
-              <span class="model-item-name">{{ model }}</span>
+              <span class="model-item-label">
+                <span class="model-item-name">{{ modelDisplayName(model, group.provider) }}</span>
+                <span v-if="modelAlias(model, group.provider)" class="model-item-id">{{ model }}</span>
+              </span>
               <span v-if="group.model_meta?.[model]?.preview" class="model-badge-preview">{{ t('models.previewBadge') }}</span>
               <span v-if="group.model_meta?.[model]?.disabled" class="model-badge-disabled">{{ t('models.disabledBadge') }}</span>
               <span v-if="customModelSet.has(model)" class="model-badge-custom">{{ t('models.customBadge') }}</span>
+              <NButton quaternary size="tiny" class="model-alias-button" @click.stop="openAliasEditor(model, group.provider)">
+                {{ t('models.aliasEdit') }}
+              </NButton>
               <svg v-if="model === appStore.selectedModel && group.provider === appStore.selectedProvider" class="model-check" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
                 <polyline points="20 6 9 17 4 12" />
               </svg>
@@ -169,6 +211,28 @@ function openModal() {
         </div>
       </div>
     </NModal>
+
+    <NModal
+      v-model:show="showAliasModal"
+      preset="card"
+      :title="aliasModel ? t('models.aliasTitleFor', { model: aliasModel }) : t('models.aliasTitle')"
+      :style="{ width: 'min(420px, calc(100vw - 32px))' }"
+      :mask-closable="true"
+    >
+      <NInput
+        v-model:value="aliasInput"
+        :placeholder="t('models.aliasPlaceholder')"
+        clearable
+        @keydown.enter="saveAlias"
+      />
+      <div class="model-alias-hint">{{ t('models.aliasHint') }}</div>
+      <template #footer>
+        <div class="model-alias-actions">
+          <NButton @click="showAliasModal = false">{{ t('common.cancel') }}</NButton>
+          <NButton type="primary" @click="saveAlias">{{ t('common.save') }}</NButton>
+        </div>
+      </template>
+    </NModal>
   </div>
 </template>
 
diff --git a/packages/client/src/i18n/locales/en.ts b/packages/client/src/i18n/locales/en.ts
index dc4c39e3..aa6525ab 100644
--- a/packages/client/src/i18n/locales/en.ts
+++ b/packages/client/src/i18n/locales/en.ts
@@ -553,6 +553,12 @@ export default {
     models: 'Models',
     count: 'models',
     more: 'more',
+    aliasEdit: 'Rename',
+    aliasTitle: 'Model display name',
+    aliasTitleFor: 'Display name for {model}',
+    aliasPlaceholder: 'Leave empty to use original model ID',
+    aliasHint: 'Display-only alias. Hermes still receives the canonical model ID.',
+    aliasSaveFailed: 'Failed to save display name',
     builtIn: 'Built-in',
     customType: 'Custom',
     provider: 'Provider',
diff --git a/packages/client/src/i18n/locales/zh.ts b/packages/client/src/i18n/locales/zh.ts
index 38efcce4..c72ef5ff 100644
--- a/packages/client/src/i18n/locales/zh.ts
+++ b/packages/client/src/i18n/locales/zh.ts
@@ -553,6 +553,12 @@ export default {
     models: '模型列表',
     count: '个模型',
     more: '个更多',
+    aliasEdit: '重命名',
+    aliasTitle: '模型显示名',
+    aliasTitleFor: '{model} 的显示名',
+    aliasPlaceholder: '留空则使用原始模型 ID',
+    aliasHint: '仅修改 Web UI 显示名，发送给 Hermes 的仍是原始模型 ID。',
+    aliasSaveFailed: '保存显示名失败',
     builtIn: '内置',
     customType: '自定义',
     provider: 'Provider',
diff --git a/packages/client/src/stores/hermes/app.ts b/packages/client/src/stores/hermes/app.ts
index 15253d1c..f5091520 100644
--- a/packages/client/src/stores/hermes/app.ts
+++ b/packages/client/src/stores/hermes/app.ts
@@ -1,6 +1,6 @@
 import { defineStore } from 'pinia'
 import { ref } from 'vue'
-import { checkHealth, fetchAvailableModels, updateDefaultModel, triggerUpdate, type AvailableModelGroup } from '@/api/hermes/system'
+import { checkHealth, fetchAvailableModels, updateDefaultModel, triggerUpdate, updateModelAlias, type AvailableModelGroup } from '@/api/hermes/system'
 
 const WEB_UI_VERSION = __APP_VERSION__
 
@@ -20,6 +20,7 @@ export const useAppStore = defineStore('app', () => {
   const selectedModel = ref('')
   const selectedProvider = ref('')
   const customModels = ref<Record<string, string[]>>({})
+  const modelAliases = ref<Record<string, Record<string, string>>>({})
   const healthPollTimer = ref<ReturnType<typeof setInterval>>()
   const nodeVersion = ref('')
 
@@ -62,6 +63,7 @@ export const useAppStore = defineStore('app', () => {
     try {
       const res = await fetchAvailableModels()
       modelGroups.value = res.groups
+      modelAliases.value = res.model_aliases || {}
       selectedModel.value = res.default
       selectedProvider.value = res.default_provider || ''
     } catch {
@@ -69,6 +71,34 @@ export const useAppStore = defineStore('app', () => {
     }
   }
 
+  function getModelAlias(modelId: string, provider?: string): string {
+    if (provider && modelAliases.value[provider]?.[modelId]) return modelAliases.value[provider][modelId]
+    for (const aliases of Object.values(modelAliases.value)) {
+      if (aliases[modelId]) return aliases[modelId]
+    }
+    return ''
+  }
+
+  function displayModelName(modelId: string, provider?: string): string {
+    return getModelAlias(modelId, provider) || modelId
+  }
+
+  async function setModelAlias(modelId: string, provider: string, alias: string) {
+    const cleanAlias = alias.trim()
+    await updateModelAlias({ provider, model: modelId, alias: cleanAlias })
+    const next = { ...modelAliases.value }
+    const providerAliases = { ...(next[provider] || {}) }
+    if (cleanAlias) {
+      providerAliases[modelId] = cleanAlias
+      next[provider] = providerAliases
+    } else {
+      delete providerAliases[modelId]
+      if (Object.keys(providerAliases).length > 0) next[provider] = providerAliases
+      else delete next[provider]
+    }
+    modelAliases.value = next
+  }
+
   async function switchModel(modelId: string, providerOverride?: string) {
     try {
       // Find the group containing this model to get provider info
@@ -134,6 +164,7 @@ export const useAppStore = defineStore('app', () => {
     doUpdate,
     modelGroups,
     customModels,
+    modelAliases,
     selectedModel,
     selectedProvider,
     streamEnabled,
@@ -142,6 +173,9 @@ export const useAppStore = defineStore('app', () => {
     checkConnection,
     loadModels,
     switchModel,
+    getModelAlias,
+    displayModelName,
+    setModelAlias,
     startHealthPolling,
     stopHealthPolling,
   }
diff --git a/packages/server/src/controllers/hermes/models.ts b/packages/server/src/controllers/hermes/models.ts
index b450e467..7b647826 100644
--- a/packages/server/src/controllers/hermes/models.ts
+++ b/packages/server/src/controllers/hermes/models.ts
@@ -4,12 +4,70 @@ import { getActiveEnvPath, getActiveAuthPath } from '../../services/hermes/herme
 import { readConfigYaml, writeConfigYaml, fetchProviderModels, buildModelGroups, PROVIDER_ENV_MAP } from '../../services/config-helpers'
 import { buildProviderModelMap, PROVIDER_PRESETS } from '../../shared/providers'
 import { getCopilotModelsDetailed, resolveCopilotOAuthToken, type CopilotModelMeta } from '../../services/hermes/copilot-models'
-import { readAppConfig } from '../../services/app-config'
+import { readAppConfig, writeAppConfig } from '../../services/app-config'
 import { getDb } from '../../db'
 import { MODEL_CONTEXT_TABLE } from '../../db/hermes/schemas'
 
 const PROVIDER_MODEL_CATALOG = buildProviderModelMap()
 
+type ModelMeta = { preview?: boolean; disabled?: boolean; alias?: string }
+type ModelGroup = {
+  provider: string
+  label: string
+  base_url: string
+  models: string[]
+  api_key: string
+  builtin?: boolean
+  model_meta?: Record<string, ModelMeta>
+}
+
+const RESERVED_ALIAS_KEYS = new Set(['__proto__', 'prototype', 'constructor'])
+
+function isSafeAliasKey(value: string): boolean {
+  const trimmed = value.trim()
+  return !!trimmed && trimmed.length <= 512 && !RESERVED_ALIAS_KEYS.has(trimmed)
+}
+
+function createAliasMap(): Record<string, string> {
+  return Object.create(null) as Record<string, string>
+}
+
+function createProviderAliasMap(): Record<string, Record<string, string>> {
+  return Object.create(null) as Record<string, Record<string, string>>
+}
+
+function normalizeAliases(value: unknown): Record<string, Record<string, string>> {
+  const normalized = createProviderAliasMap()
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return normalized
+  for (const [provider, models] of Object.entries(value as Record<string, unknown>)) {
+    if (!isSafeAliasKey(provider) || !models || typeof models !== 'object' || Array.isArray(models)) continue
+    for (const [model, alias] of Object.entries(models as Record<string, unknown>)) {
+      if (!isSafeAliasKey(model) || typeof alias !== 'string') continue
+      const trimmed = alias.trim()
+      if (!trimmed || trimmed.length > 512) continue
+      if (!Object.hasOwn(normalized, provider)) normalized[provider] = createAliasMap()
+      normalized[provider][model] = trimmed
+    }
+  }
+  return normalized
+}
+
+function applyModelAliases<T extends { provider: string; models: string[]; model_meta?: Record<string, ModelMeta> }>(groups: T[], aliases: Record<string, Record<string, string>>): T[] {
+  return groups.map((group) => {
+    const providerAliases = aliases[group.provider]
+    if (!providerAliases) return group
+    const modelMeta: Record<string, ModelMeta> = { ...(group.model_meta || {}) }
+    let changed = false
+    for (const model of group.models) {
+      const alias = providerAliases[model]
+      if (!alias) continue
+      modelMeta[model] = { ...(modelMeta[model] || {}), alias }
+      changed = true
+    }
+    return changed ? { ...group, model_meta: modelMeta } : group
+  })
+}
+
 // Copilot 授权检测：复用同一套 token 解析逻辑（含 ~/.config/github-copilot/apps.json
 // 与 ghp_ PAT 跳过），与 getCopilotModels 行为一致，避免出现"模型能拉到却被判未授权"。
 async function isCopilotAuthorized(envContent: string): Promise<boolean> {
@@ -41,7 +99,7 @@ export async function getAvailable(ctx: any) {
       currentDefault = modelSection.trim()
     }
 
-    const groups: Array<{ provider: string; label: string; base_url: string; models: string[]; api_key: string; builtin?: boolean; model_meta?: Record<string, { preview?: boolean; disabled?: boolean }> }> = []
+    const groups: ModelGroup[] = []
     const seenProviders = new Set<string>()
 
     let envContent = ''
@@ -57,7 +115,7 @@ export async function getAvailable(ctx: any) {
       const match = envContent.match(new RegExp(`^${key}\\s*=\\s*(.+)`, 'm'))
       return match?.[1]?.trim() || ''
     }
-    const addGroup = (provider: string, label: string, base_url: string, models: string[], api_key: string, builtin?: boolean, model_meta?: Record<string, { preview?: boolean; disabled?: boolean }>) => {
+    const addGroup = (provider: string, label: string, base_url: string, models: string[], api_key: string, builtin?: boolean, model_meta?: Record<string, ModelMeta>) => {
       if (seenProviders.has(provider)) return
       seenProviders.add(provider)
       groups.push({ provider, label, base_url, models: [...models], api_key, ...(builtin ? { builtin: true } : {}), ...(model_meta ? { model_meta } : {}) })
@@ -93,6 +151,7 @@ export async function getAvailable(ctx: any) {
     // 时也不返回。避免误把 VS Code/gh CLI 用户的全局凭证当作 hermes provider。
     const appConfig = await readAppConfig()
     const copilotEnabled = appConfig.copilotEnabled === true
+    const modelAliases = normalizeAliases(appConfig.modelAliases)
 
     // 兼容老用户：上一版本会"自动 fallback discovery"出 Copilot；升级后这些用户的
     // config.yaml 可能仍把 model.default 指向某个 copilot 模型。若此时 copilot 已不
@@ -120,7 +179,7 @@ export async function getAvailable(ctx: any) {
       }
       const catalogModels = PROVIDER_MODEL_CATALOG[providerKey]
       let modelsList: string[] = catalogModels && catalogModels.length > 0 ? [...catalogModels] : []
-      let modelMeta: Record<string, { preview?: boolean; disabled?: boolean }> | undefined
+      let modelMeta: Record<string, ModelMeta> | undefined
       if (providerKey === 'copilot') {
         const live = await getCopilotLive()
         if (live.length > 0) {
@@ -196,14 +255,74 @@ export async function getAvailable(ctx: any) {
       base_url: p.base_url,
       models: p.value === 'copilot' && liveCopilotIds.length > 0 ? liveCopilotIds : p.models,
     }))
+    const allProviders = applyModelAliases(allProvidersBase, modelAliases)
 
     if (groups.length === 0) {
       const fallback = buildModelGroups(config)
-      ctx.body = { ...fallback, allProviders: allProvidersBase }
+      ctx.body = {
+        ...fallback,
+        allProviders,
+        model_aliases: modelAliases,
+      }
       return
     }
 
-    ctx.body = { default: currentDefault, default_provider: currentDefaultProvider, groups, allProviders: allProvidersBase }
+    ctx.body = {
+      default: currentDefault,
+      default_provider: currentDefaultProvider,
+      groups: applyModelAliases(groups, modelAliases),
+      allProviders,
+      model_aliases: modelAliases,
+    }
+  } catch (err: any) {
+    ctx.status = 500
+    ctx.body = { error: err.message }
+  }
+}
+
+
+export async function setModelAlias(ctx: any) {
+  const body = ctx.request.body
+  const provider = body && typeof body === 'object' && !Array.isArray(body) ? body.provider : undefined
+  const model = body && typeof body === 'object' && !Array.isArray(body) ? body.model : undefined
+  const alias = body && typeof body === 'object' && !Array.isArray(body) ? body.alias : undefined
+
+  if (typeof provider !== 'string' || typeof model !== 'string' || (alias !== undefined && typeof alias !== 'string')) {
+    ctx.status = 400
+    ctx.body = { error: 'Invalid provider, model, or alias' }
+    return
+  }
+
+  const cleanProvider = provider.trim()
+  const cleanModel = model.trim()
+  const cleanAlias = (alias || '').trim()
+
+  if (!isSafeAliasKey(cleanProvider) || !isSafeAliasKey(cleanModel)) {
+    ctx.status = 400
+    ctx.body = { error: 'Invalid provider or model' }
+    return
+  }
+
+  if (cleanAlias.length > 512) {
+    ctx.status = 400
+    ctx.body = { error: 'Alias is too long' }
+    return
+  }
+
+  try {
+    const appConfig = await readAppConfig()
+    const modelAliases = normalizeAliases(appConfig.modelAliases)
+    if (cleanAlias) {
+      if (!Object.hasOwn(modelAliases, cleanProvider)) modelAliases[cleanProvider] = createAliasMap()
+      modelAliases[cleanProvider][cleanModel] = cleanAlias
+    } else {
+      if (Object.hasOwn(modelAliases, cleanProvider)) delete modelAliases[cleanProvider][cleanModel]
+      if (Object.hasOwn(modelAliases, cleanProvider) && Object.keys(modelAliases[cleanProvider]).length === 0) {
+        delete modelAliases[cleanProvider]
+      }
+    }
+    await writeAppConfig({ modelAliases })
+    ctx.body = { success: true, model_aliases: modelAliases }
   } catch (err: any) {
     ctx.status = 500
     ctx.body = { error: err.message }
diff --git a/packages/server/src/routes/hermes/models.ts b/packages/server/src/routes/hermes/models.ts
index 9b98de9b..716607a1 100644
--- a/packages/server/src/routes/hermes/models.ts
+++ b/packages/server/src/routes/hermes/models.ts
@@ -6,6 +6,7 @@ export const modelRoutes = new Router()
 modelRoutes.get('/api/hermes/available-models', ctrl.getAvailable)
 modelRoutes.get('/api/hermes/config/models', ctrl.getConfigModels)
 modelRoutes.put('/api/hermes/config/model', ctrl.setConfigModel)
+modelRoutes.put('/api/hermes/model-alias', ctrl.setModelAlias)
 
 // Model context routes
 modelRoutes.get('/api/hermes/model-context', ctrl.getModelContext)
diff --git a/packages/server/src/services/app-config.ts b/packages/server/src/services/app-config.ts
index e6314cdb..b6ec4ba5 100644
--- a/packages/server/src/services/app-config.ts
+++ b/packages/server/src/services/app-config.ts
@@ -12,6 +12,10 @@ export interface AppConfig {
   // via "Add Provider". Mirrors how the user manages Codex/Nous: the web-ui
   // owns the provider list, system credentials are merely a fallback source.
   copilotEnabled?: boolean
+
+  // Web UI-only model display aliases. Keys are provider -> canonical model ID -> display label.
+  // These aliases never replace the canonical model ID sent back to Hermes.
+  modelAliases?: Record<string, Record<string, string>>
 }
 
 let cache: AppConfig | null = null
diff --git a/tests/client/app-store.test.ts b/tests/client/app-store.test.ts
index d2ac26be..dcd32953 100644
--- a/tests/client/app-store.test.ts
+++ b/tests/client/app-store.test.ts
@@ -6,6 +6,7 @@ const mockSystemApi = vi.hoisted(() => ({
   checkHealth: vi.fn(),
   fetchAvailableModels: vi.fn(),
   updateDefaultModel: vi.fn(),
+  updateModelAlias: vi.fn(),
   triggerUpdate: vi.fn(),
 }))
 
@@ -46,4 +47,47 @@ describe('App Store', () => {
     expect(consoleError).toHaveBeenCalledWith('Failed to update Hermes Web UI:', expect.any(Error))
     consoleError.mockRestore()
   })
+
+  it('loads model aliases and resolves display names without changing canonical IDs', async () => {
+    mockSystemApi.fetchAvailableModels.mockResolvedValue({
+      default: 'deepseek-v4-flash',
+      default_provider: 'deepseek',
+      groups: [{
+        provider: 'deepseek',
+        label: 'DeepSeek',
+        base_url: 'https://api.deepseek.com/v1',
+        models: ['deepseek-v4-flash'],
+        api_key: '',
+      }],
+      allProviders: [],
+      model_aliases: {
+        deepseek: { 'deepseek-v4-flash': 'Flash Alias' },
+      },
+    })
+    const store = useAppStore()
+
+    await store.loadModels()
+
+    expect(store.selectedModel).toBe('deepseek-v4-flash')
+    expect(store.getModelAlias('deepseek-v4-flash', 'deepseek')).toBe('Flash Alias')
+    expect(store.displayModelName('deepseek-v4-flash', 'deepseek')).toBe('Flash Alias')
+    expect(store.displayModelName('unknown', 'deepseek')).toBe('unknown')
+  })
+
+  it('saves and clears model aliases via the Web UI-only alias API', async () => {
+    mockSystemApi.updateModelAlias.mockResolvedValue(undefined)
+    const store = useAppStore()
+
+    await store.setModelAlias('deepseek-v4-flash', 'deepseek', '  Flash Alias  ')
+
+    expect(mockSystemApi.updateModelAlias).toHaveBeenCalledWith({
+      provider: 'deepseek',
+      model: 'deepseek-v4-flash',
+      alias: 'Flash Alias',
+    })
+    expect(store.modelAliases).toEqual({ deepseek: { 'deepseek-v4-flash': 'Flash Alias' } })
+
+    await store.setModelAlias('deepseek-v4-flash', 'deepseek', '')
+    expect(store.modelAliases).toEqual({})
+  })
 })
diff --git a/tests/server/model-alias-controller.test.ts b/tests/server/model-alias-controller.test.ts
new file mode 100644
index 00000000..4fad9a04
--- /dev/null
+++ b/tests/server/model-alias-controller.test.ts
@@ -0,0 +1,130 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { mockReadAppConfig, mockWriteAppConfig } = vi.hoisted(() => ({
+  mockReadAppConfig: vi.fn(),
+  mockWriteAppConfig: vi.fn(),
+}))
+
+vi.mock('../../packages/server/src/services/app-config', () => ({
+  readAppConfig: mockReadAppConfig,
+  writeAppConfig: mockWriteAppConfig,
+}))
+
+vi.mock('../../packages/server/src/services/config-helpers', () => ({
+  readConfigYaml: vi.fn(),
+  writeConfigYaml: vi.fn(),
+  fetchProviderModels: vi.fn(),
+  buildModelGroups: vi.fn(() => ({ default: '', default_provider: '', groups: [] })),
+  PROVIDER_ENV_MAP: {},
+}))
+
+vi.mock('../../packages/server/src/shared/providers', () => ({
+  buildProviderModelMap: vi.fn(() => ({})),
+  PROVIDER_PRESETS: [],
+}))
+
+vi.mock('../../packages/server/src/services/hermes/copilot-models', () => ({
+  getCopilotModelsDetailed: vi.fn(),
+  resolveCopilotOAuthToken: vi.fn(),
+}))
+
+vi.mock('../../packages/server/src/db', () => ({
+  getDb: vi.fn(),
+}))
+
+vi.mock('../../packages/server/src/db/hermes/schemas', () => ({
+  MODEL_CONTEXT_TABLE: 'model_context',
+}))
+
+import { setModelAlias } from '../../packages/server/src/controllers/hermes/models'
+
+describe('model alias controller', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockWriteAppConfig.mockResolvedValue({})
+  })
+
+  function createCtx(body: unknown) {
+    return {
+      request: { body },
+      status: 200,
+      body: undefined as unknown,
+    }
+  }
+
+  it('saves a trimmed alias in Web UI app config', async () => {
+    mockReadAppConfig.mockResolvedValue({
+      modelAliases: {
+        deepseek: { old: 'Old Alias' },
+      },
+    })
+    const ctx = createCtx({ provider: 'deepseek', model: 'deepseek-v4-flash', alias: '  Flash Alias  ' })
+
+    await setModelAlias(ctx)
+
+    expect(mockWriteAppConfig).toHaveBeenCalledWith({
+      modelAliases: {
+        deepseek: {
+          old: 'Old Alias',
+          'deepseek-v4-flash': 'Flash Alias',
+        },
+      },
+    })
+    expect(ctx.body).toEqual({
+      success: true,
+      model_aliases: {
+        deepseek: {
+          old: 'Old Alias',
+          'deepseek-v4-flash': 'Flash Alias',
+        },
+      },
+    })
+  })
+
+  it('deletes an alias when alias is blank and removes empty provider entries', async () => {
+    mockReadAppConfig.mockResolvedValue({
+      modelAliases: {
+        deepseek: { 'deepseek-v4-flash': 'Flash Alias' },
+      },
+    })
+    const ctx = createCtx({ provider: 'deepseek', model: 'deepseek-v4-flash', alias: '   ' })
+
+    await setModelAlias(ctx)
+
+    expect(mockWriteAppConfig).toHaveBeenCalledWith({ modelAliases: {} })
+    expect(ctx.body).toEqual({ success: true, model_aliases: {} })
+  })
+
+  it('rejects missing provider or model', async () => {
+    const ctx = createCtx({ provider: 'deepseek', alias: 'Alias' })
+
+    await setModelAlias(ctx)
+
+    expect(ctx.status).toBe(400)
+    expect(ctx.body).toEqual({ error: 'Invalid provider, model, or alias' })
+    expect(mockWriteAppConfig).not.toHaveBeenCalled()
+  })
+
+  it('stores inherited Object.prototype names as own alias keys', async () => {
+    mockReadAppConfig.mockResolvedValue({})
+    const ctx = createCtx({ provider: 'toString', model: 'valueOf', alias: 'Safe Alias' })
+
+    await setModelAlias(ctx)
+
+    const written = mockWriteAppConfig.mock.calls[0][0]
+    expect(written.modelAliases.toString.valueOf).toBe('Safe Alias')
+    expect(Object.prototype.hasOwnProperty.call(written.modelAliases, 'toString')).toBe(true)
+    expect(Object.prototype.hasOwnProperty.call(written.modelAliases.toString, 'valueOf')).toBe(true)
+  })
+
+  it('rejects reserved object keys to avoid prototype pollution', async () => {
+    const ctx = createCtx({ provider: '__proto__', model: 'deepseek-v4-flash', alias: 'Alias' })
+
+    await setModelAlias(ctx)
+
+    expect(ctx.status).toBe(400)
+    expect(ctx.body).toEqual({ error: 'Invalid provider or model' })
+    expect(mockWriteAppConfig).not.toHaveBeenCalled()
+    expect(({} as Record<string, unknown>).deepseek).toBeUndefined()
+  })
+})

From f62d291bba04f8ff096e5438d445050ba74ef450 Mon Sep 17 00:00:00 2001
From: Zhicheng Han <zhicheng.han@mathematik.uni-goettingen.de>
Date: Sun, 10 May 2026 20:13:42 +0200
Subject: [PATCH 2/4] fix(models): improve WUI model alias editing

---
 .../components/hermes/models/ProviderCard.vue | 205 +++++++++++++++++-
 .../src/components/layout/ModelSelector.vue   |  58 ++++-
 packages/client/src/i18n/locales/en.ts        |   4 +
 packages/client/src/i18n/locales/zh.ts        |   4 +
 .../client/src/views/hermes/ModelsView.vue    |   4 +-
 5 files changed, 265 insertions(+), 10 deletions(-)

diff --git a/packages/client/src/components/hermes/models/ProviderCard.vue b/packages/client/src/components/hermes/models/ProviderCard.vue
index 2dc9d02e..2f90b255 100644
--- a/packages/client/src/components/hermes/models/ProviderCard.vue
+++ b/packages/client/src/components/hermes/models/ProviderCard.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { ref, computed } from 'vue'
-import { NButton, useMessage, useDialog } from 'naive-ui'
+import { NButton, NModal, NInput, useMessage, useDialog } from 'naive-ui'
 import type { AvailableModelGroup } from '@/api/hermes/system'
 import { useModelsStore } from '@/stores/hermes/models'
 import { useAppStore } from '@/stores/hermes/app'
@@ -21,6 +21,41 @@ const isCustom = computed(() => !props.provider.builtin && props.provider.provid
 const isCopilot = computed(() => props.provider.provider === 'copilot')
 const displayName = computed(() => props.provider.label)
 const deleting = ref(false)
+const showAliasListModal = ref(false)
+const showAliasModal = ref(false)
+const aliasProvider = ref('')
+const aliasModel = ref('')
+const aliasInput = ref('')
+
+function modelAlias(model: string) {
+  return appStore.getModelAlias(model, props.provider.provider)
+}
+
+function modelDisplayName(model: string) {
+  return appStore.displayModelName(model, props.provider.provider)
+}
+
+function openAliasEditor(model: string) {
+  aliasProvider.value = props.provider.provider
+  aliasModel.value = model
+  aliasInput.value = appStore.getModelAlias(model, props.provider.provider)
+  showAliasModal.value = true
+}
+
+async function saveAlias() {
+  if (!aliasModel.value || !aliasProvider.value) return
+  try {
+    await appStore.setModelAlias(aliasModel.value, aliasProvider.value, aliasInput.value)
+    showAliasModal.value = false
+  } catch (e: any) {
+    message.error(e.message || t('models.aliasSaveFailed'))
+  }
+}
+
+async function clearAlias() {
+  aliasInput.value = ''
+  await saveAlias()
+}
 
 async function handleDelete() {
   let copilotMsg = ''
@@ -96,11 +131,18 @@ async function handleDelete() {
         <span class="info-value models-count">{{ provider.models.length }} {{ t('models.count') }}</span>
       </div>
       <div class="models-list">
-        <span
+        <button
           v-for="model in provider.models.slice(0, 20)"
           :key="model"
-          class="model-tag"
-        >{{ model }}</span>
+          class="model-tag model-tag-button"
+          type="button"
+          :title="t('models.aliasTitleFor', { model })"
+          @click="openAliasEditor(model)"
+        >
+          <span class="model-tag-name">{{ modelDisplayName(model) }}</span>
+          <span v-if="modelAlias(model)" class="model-tag-id">{{ model }}</span>
+          <span class="model-tag-edit">{{ t('models.aliasEdit') }}</span>
+        </button>
         <span v-if="provider.models.length > 20" class="model-tag model-tag-more">
           +{{ provider.models.length - 20 }} {{ t('models.more') }}
         </span>
@@ -108,8 +150,57 @@ async function handleDelete() {
     </div>
 
     <div class="card-actions">
+      <NButton size="tiny" quaternary @click="showAliasListModal = true">{{ t('models.aliasManage') }}</NButton>
       <NButton size="tiny" quaternary type="error" :loading="deleting" @click="handleDelete">{{ t('common.delete') }}</NButton>
     </div>
+
+    <NModal
+      v-model:show="showAliasListModal"
+      preset="card"
+      :title="t('models.aliasManageFor', { provider: displayName })"
+      :style="{ width: 'min(560px, calc(100vw - 32px))' }"
+      :mask-closable="true"
+    >
+      <div class="alias-list-hint">{{ t('models.aliasHint') }}</div>
+      <div class="alias-list">
+        <div v-for="model in provider.models" :key="model" class="alias-row">
+          <div class="alias-row-text">
+            <span class="alias-row-name">{{ modelDisplayName(model) }}</span>
+            <code class="alias-row-id">{{ model }}</code>
+          </div>
+          <NButton size="tiny" quaternary @click="openAliasEditor(model)">{{ t('models.aliasEdit') }}</NButton>
+        </div>
+      </div>
+    </NModal>
+
+    <NModal
+      v-model:show="showAliasModal"
+      preset="card"
+      :title="aliasModel ? t('models.aliasTitleFor', { model: aliasModel }) : t('models.aliasTitle')"
+      :style="{ width: 'min(420px, calc(100vw - 32px))' }"
+      :mask-closable="true"
+    >
+      <NInput
+        v-model:value="aliasInput"
+        :placeholder="t('models.aliasPlaceholder')"
+        clearable
+        @keydown.enter="saveAlias"
+      />
+      <div v-if="aliasModel" class="model-alias-canonical">
+        {{ t('models.aliasCanonical', { model: aliasModel }) }}
+      </div>
+      <div class="model-alias-hint">{{ t('models.aliasHint') }}</div>
+      <template #footer>
+        <div class="model-alias-actions">
+          <NButton quaternary :disabled="!appStore.getModelAlias(aliasModel, aliasProvider)" @click="clearAlias">
+            {{ t('models.aliasUseOriginal') }}
+          </NButton>
+          <div class="model-alias-spacer" />
+          <NButton @click="showAliasModal = false">{{ t('common.cancel') }}</NButton>
+          <NButton type="primary" @click="saveAlias">{{ t('common.save') }}</NButton>
+        </div>
+      </template>
+    </NModal>
   </div>
 </template>
 
@@ -212,7 +303,8 @@ async function handleDelete() {
 .model-tag {
   display: inline-flex;
   align-items: center;
-  height: 20px;
+  gap: 5px;
+  min-height: 22px;
   font-size: 10px;
   font-family: $font-code;
   padding: 2px 6px;
@@ -220,7 +312,7 @@ async function handleDelete() {
   background: rgba(var(--accent-primary-rgb), 0.08);
   color: $text-secondary;
   white-space: nowrap;
-  max-width: 200px;
+  max-width: 260px;
   overflow: hidden;
   text-overflow: ellipsis;
 
@@ -231,10 +323,111 @@ async function handleDelete() {
   }
 }
 
+.model-tag-button {
+  border: 0;
+  cursor: pointer;
+  text-align: left;
+
+  &:hover {
+    background: rgba(var(--accent-primary-rgb), 0.16);
+    color: $text-primary;
+  }
+}
+
+.model-tag-name,
+.model-tag-id {
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.model-tag-id {
+  color: $text-muted;
+  font-size: 9px;
+}
+
+.model-tag-edit {
+  flex-shrink: 0;
+  color: $accent-primary;
+  font-family: $font-ui;
+  font-size: 9px;
+}
+
 .card-actions {
   display: flex;
   gap: 8px;
   border-top: 1px solid $border-light;
   padding-top: 10px;
 }
+
+.alias-list-hint,
+.model-alias-hint {
+  color: $text-muted;
+  font-size: 12px;
+}
+
+.alias-list-hint {
+  margin-bottom: 12px;
+}
+
+.alias-list {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  max-height: 45vh;
+  overflow-y: auto;
+}
+
+.alias-row {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 8px;
+  border: 1px solid $border-light;
+  border-radius: $radius-sm;
+}
+
+.alias-row-text {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.alias-row-name {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: $text-primary;
+  font-family: $font-code;
+  font-size: 12px;
+}
+
+.alias-row-id,
+.model-alias-canonical {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: $text-muted;
+  font-family: $font-code;
+  font-size: 11px;
+}
+
+.model-alias-canonical {
+  margin-top: 8px;
+}
+
+.model-alias-hint {
+  margin-top: 6px;
+}
+
+.model-alias-actions {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.model-alias-spacer {
+  flex: 1;
+}
 </style>
diff --git a/packages/client/src/components/layout/ModelSelector.vue b/packages/client/src/components/layout/ModelSelector.vue
index cf0bdeb4..521199ff 100644
--- a/packages/client/src/components/layout/ModelSelector.vue
+++ b/packages/client/src/components/layout/ModelSelector.vue
@@ -100,6 +100,11 @@ async function saveAlias() {
   }
 }
 
+async function clearAlias() {
+  aliasInput.value = ''
+  await saveAlias()
+}
+
 function handleCustomSubmit() {
   const model = customInput.value.trim()
   if (!model || !customProvider.value) return
@@ -172,7 +177,9 @@ function openModal() {
             >
               <span class="model-item-label">
                 <span class="model-item-name">{{ modelDisplayName(model, group.provider) }}</span>
-                <span v-if="modelAlias(model, group.provider)" class="model-item-id">{{ model }}</span>
+                <span v-if="modelAlias(model, group.provider)" class="model-item-id">
+                  {{ t('models.aliasCanonical', { model }) }}
+                </span>
               </span>
               <span v-if="group.model_meta?.[model]?.preview" class="model-badge-preview">{{ t('models.previewBadge') }}</span>
               <span v-if="group.model_meta?.[model]?.disabled" class="model-badge-disabled">{{ t('models.disabledBadge') }}</span>
@@ -225,9 +232,16 @@ function openModal() {
         clearable
         @keydown.enter="saveAlias"
       />
+      <div v-if="aliasModel" class="model-alias-canonical">
+        {{ t('models.aliasCanonical', { model: aliasModel }) }}
+      </div>
       <div class="model-alias-hint">{{ t('models.aliasHint') }}</div>
       <template #footer>
         <div class="model-alias-actions">
+          <NButton quaternary :disabled="!appStore.getModelAlias(aliasModel, aliasProvider)" @click="clearAlias">
+            {{ t('models.aliasUseOriginal') }}
+          </NButton>
+          <div class="model-alias-spacer" />
           <NButton @click="showAliasModal = false">{{ t('common.cancel') }}</NButton>
           <NButton type="primary" @click="saveAlias">{{ t('common.save') }}</NButton>
         </div>
@@ -372,8 +386,15 @@ function openModal() {
   }
 }
 
-.model-item-name {
+.model-item-label {
   flex: 1;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.model-item-name {
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
@@ -381,6 +402,39 @@ function openModal() {
   font-size: 12px;
 }
 
+.model-item-id {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: $text-muted;
+  font-family: $font-code;
+  font-size: 10px;
+  font-weight: 400;
+}
+
+.model-alias-canonical {
+  margin-top: 8px;
+  color: $text-muted;
+  font-family: $font-code;
+  font-size: 11px;
+}
+
+.model-alias-hint {
+  margin-top: 6px;
+  color: $text-muted;
+  font-size: 12px;
+}
+
+.model-alias-actions {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.model-alias-spacer {
+  flex: 1;
+}
+
 .model-check {
   flex-shrink: 0;
   color: $accent-primary;
diff --git a/packages/client/src/i18n/locales/en.ts b/packages/client/src/i18n/locales/en.ts
index aa6525ab..0d20636c 100644
--- a/packages/client/src/i18n/locales/en.ts
+++ b/packages/client/src/i18n/locales/en.ts
@@ -558,6 +558,10 @@ export default {
     aliasTitleFor: 'Display name for {model}',
     aliasPlaceholder: 'Leave empty to use original model ID',
     aliasHint: 'Display-only alias. Hermes still receives the canonical model ID.',
+    aliasCanonical: 'Original ID: {model}',
+    aliasUseOriginal: 'Use original ID',
+    aliasManage: 'Display names',
+    aliasManageFor: 'Display names for {provider}',
     aliasSaveFailed: 'Failed to save display name',
     builtIn: 'Built-in',
     customType: 'Custom',
diff --git a/packages/client/src/i18n/locales/zh.ts b/packages/client/src/i18n/locales/zh.ts
index c72ef5ff..4dc728d2 100644
--- a/packages/client/src/i18n/locales/zh.ts
+++ b/packages/client/src/i18n/locales/zh.ts
@@ -558,6 +558,10 @@ export default {
     aliasTitleFor: '{model} 的显示名',
     aliasPlaceholder: '留空则使用原始模型 ID',
     aliasHint: '仅修改 Web UI 显示名，发送给 Hermes 的仍是原始模型 ID。',
+    aliasCanonical: '原始 ID：{model}',
+    aliasUseOriginal: '恢复原始 ID',
+    aliasManage: '显示名',
+    aliasManageFor: '{provider} 的显示名',
     aliasSaveFailed: '保存显示名失败',
     builtIn: '内置',
     customType: '自定义',
diff --git a/packages/client/src/views/hermes/ModelsView.vue b/packages/client/src/views/hermes/ModelsView.vue
index e335b31c..caae2d2c 100644
--- a/packages/client/src/views/hermes/ModelsView.vue
+++ b/packages/client/src/views/hermes/ModelsView.vue
@@ -15,9 +15,9 @@ const showModal = ref(false)
 
 onMounted(async () => {
   // 先 invalidate 后端 copilot 缓存（gh logout / VS Code 退出后下一次 list 立刻反映），
-  // 再拉 providers。check-token 失败不阻断。
+  // 再拉 providers 与 appStore 的模型显示名配置。check-token 失败不阻断。
   try { await checkCopilotToken() } catch { /* ignore */ }
-  modelsStore.fetchProviders()
+  await Promise.all([modelsStore.fetchProviders(), appStore.loadModels()])
 })
 
 function openCreateModal() {

From 65f7ec2efaca83d17ba46ba799ba79482e6c2814 Mon Sep 17 00:00:00 2001
From: Zhicheng Han <zhicheng.han@mathematik.uni-goettingen.de>
Date: Sun, 10 May 2026 20:43:04 +0200
Subject: [PATCH 3/4] fix(models): clarify unlisted model picker

---
 .../components/hermes/models/ProviderCard.vue |   8 --
 .../src/components/layout/ModelSelector.vue   | 127 +++++-------------
 packages/client/src/i18n/locales/en.ts        |   5 +-
 packages/client/src/i18n/locales/zh.ts        |   5 +-
 packages/client/src/stores/hermes/app.ts      |  23 ++++
 tests/client/app-store.test.ts                |  24 ++++
 6 files changed, 90 insertions(+), 102 deletions(-)

diff --git a/packages/client/src/components/hermes/models/ProviderCard.vue b/packages/client/src/components/hermes/models/ProviderCard.vue
index 2f90b255..1b3ddbdb 100644
--- a/packages/client/src/components/hermes/models/ProviderCard.vue
+++ b/packages/client/src/components/hermes/models/ProviderCard.vue
@@ -141,7 +141,6 @@ async function handleDelete() {
         >
           <span class="model-tag-name">{{ modelDisplayName(model) }}</span>
           <span v-if="modelAlias(model)" class="model-tag-id">{{ model }}</span>
-          <span class="model-tag-edit">{{ t('models.aliasEdit') }}</span>
         </button>
         <span v-if="provider.models.length > 20" class="model-tag model-tag-more">
           +{{ provider.models.length - 20 }} {{ t('models.more') }}
@@ -345,13 +344,6 @@ async function handleDelete() {
   font-size: 9px;
 }
 
-.model-tag-edit {
-  flex-shrink: 0;
-  color: $accent-primary;
-  font-family: $font-ui;
-  font-size: 9px;
-}
-
 .card-actions {
   display: flex;
   gap: 8px;
diff --git a/packages/client/src/components/layout/ModelSelector.vue b/packages/client/src/components/layout/ModelSelector.vue
index 521199ff..7d456da7 100644
--- a/packages/client/src/components/layout/ModelSelector.vue
+++ b/packages/client/src/components/layout/ModelSelector.vue
@@ -1,22 +1,17 @@
 <script setup lang="ts">
 import { ref, computed } from 'vue'
-import { NButton, NModal, NInput, NSelect, useMessage } from 'naive-ui'
+import { NModal, NInput, NSelect } from 'naive-ui'
 import { useAppStore } from '@/stores/hermes/app'
 import { useI18n } from 'vue-i18n'
 
 const { t } = useI18n()
 const appStore = useAppStore()
-const message = useMessage()
 
 const showModal = ref(false)
 const searchQuery = ref('')
 const collapsedGroups = ref<Record<string, boolean>>({})
 const customInput = ref('')
 const customProvider = ref('')
-const showAliasModal = ref(false)
-const aliasProvider = ref('')
-const aliasModel = ref('')
-const aliasInput = ref('')
 
 const selectedDisplayName = computed(() => appStore.displayModelName(appStore.selectedModel, appStore.selectedProvider))
 
@@ -36,13 +31,13 @@ const modelGroupsWithCustom = computed(() =>
   }))
 )
 
-const customModelSet = computed(() => {
-  const set = new Set<string>()
-  for (const models of Object.values(appStore.customModels)) {
-    models.forEach(m => set.add(m))
-  }
-  return set
-})
+function isCustomModel(model: string, provider: string) {
+  return (appStore.customModels[provider] || []).includes(model)
+}
+
+async function removeCustomModel(model: string, provider: string) {
+  await appStore.removeCustomModel(model, provider)
+}
 
 const filteredGroups = computed(() => {
   const q = searchQuery.value.toLowerCase().trim()
@@ -82,29 +77,6 @@ function modelAlias(model: string, provider: string) {
   return appStore.getModelAlias(model, provider)
 }
 
-function openAliasEditor(model: string, provider: string) {
-  aliasModel.value = model
-  aliasProvider.value = provider
-  aliasInput.value = appStore.getModelAlias(model, provider)
-  showAliasModal.value = true
-}
-
-async function saveAlias() {
-  if (!aliasModel.value || !aliasProvider.value) return
-  try {
-    await appStore.setModelAlias(aliasModel.value, aliasProvider.value, aliasInput.value)
-    showAliasModal.value = false
-  } catch (err) {
-    console.error('Failed to save model alias:', err)
-    message.error(t('models.aliasSaveFailed'))
-  }
-}
-
-async function clearAlias() {
-  aliasInput.value = ''
-  await saveAlias()
-}
-
 function handleCustomSubmit() {
   const model = customInput.value.trim()
   if (!model || !customProvider.value) return
@@ -183,10 +155,16 @@ function openModal() {
               </span>
               <span v-if="group.model_meta?.[model]?.preview" class="model-badge-preview">{{ t('models.previewBadge') }}</span>
               <span v-if="group.model_meta?.[model]?.disabled" class="model-badge-disabled">{{ t('models.disabledBadge') }}</span>
-              <span v-if="customModelSet.has(model)" class="model-badge-custom">{{ t('models.customBadge') }}</span>
-              <NButton quaternary size="tiny" class="model-alias-button" @click.stop="openAliasEditor(model, group.provider)">
-                {{ t('models.aliasEdit') }}
-              </NButton>
+              <span v-if="isCustomModel(model, group.provider)" class="model-badge-custom">{{ t('models.customBadge') }}</span>
+              <button
+                v-if="isCustomModel(model, group.provider)"
+                class="model-custom-remove"
+                type="button"
+                :title="t('models.removeCustomModel')"
+                @click.stop="removeCustomModel(model, group.provider)"
+              >
+                ×
+              </button>
               <svg v-if="model === appStore.selectedModel && group.provider === appStore.selectedProvider" class="model-check" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
                 <polyline points="20 6 9 17 4 12" />
               </svg>
@@ -219,34 +197,6 @@ function openModal() {
       </div>
     </NModal>
 
-    <NModal
-      v-model:show="showAliasModal"
-      preset="card"
-      :title="aliasModel ? t('models.aliasTitleFor', { model: aliasModel }) : t('models.aliasTitle')"
-      :style="{ width: 'min(420px, calc(100vw - 32px))' }"
-      :mask-closable="true"
-    >
-      <NInput
-        v-model:value="aliasInput"
-        :placeholder="t('models.aliasPlaceholder')"
-        clearable
-        @keydown.enter="saveAlias"
-      />
-      <div v-if="aliasModel" class="model-alias-canonical">
-        {{ t('models.aliasCanonical', { model: aliasModel }) }}
-      </div>
-      <div class="model-alias-hint">{{ t('models.aliasHint') }}</div>
-      <template #footer>
-        <div class="model-alias-actions">
-          <NButton quaternary :disabled="!appStore.getModelAlias(aliasModel, aliasProvider)" @click="clearAlias">
-            {{ t('models.aliasUseOriginal') }}
-          </NButton>
-          <div class="model-alias-spacer" />
-          <NButton @click="showAliasModal = false">{{ t('common.cancel') }}</NButton>
-          <NButton type="primary" @click="saveAlias">{{ t('common.save') }}</NButton>
-        </div>
-      </template>
-    </NModal>
   </div>
 </template>
 
@@ -412,28 +362,6 @@ function openModal() {
   font-weight: 400;
 }
 
-.model-alias-canonical {
-  margin-top: 8px;
-  color: $text-muted;
-  font-family: $font-code;
-  font-size: 11px;
-}
-
-.model-alias-hint {
-  margin-top: 6px;
-  color: $text-muted;
-  font-size: 12px;
-}
-
-.model-alias-actions {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-}
-
-.model-alias-spacer {
-  flex: 1;
-}
 
 .model-check {
   flex-shrink: 0;
@@ -452,6 +380,25 @@ function openModal() {
   letter-spacing: 0.03em;
 }
 
+
+.model-custom-remove {
+  flex-shrink: 0;
+  width: 18px;
+  height: 18px;
+  border: 0;
+  border-radius: 50%;
+  background: transparent;
+  color: $text-muted;
+  cursor: pointer;
+  line-height: 18px;
+  padding: 0;
+
+  &:hover {
+    background: rgba(var(--error-rgb), 0.12);
+    color: $error;
+  }
+}
+
 .model-badge-preview {
   flex-shrink: 0;
   font-size: 9px;
diff --git a/packages/client/src/i18n/locales/en.ts b/packages/client/src/i18n/locales/en.ts
index 0d20636c..252ac4eb 100644
--- a/packages/client/src/i18n/locales/en.ts
+++ b/packages/client/src/i18n/locales/en.ts
@@ -547,8 +547,9 @@ export default {
     previewBadge: 'PREVIEW',
     disabledBadge: 'UNAVAILABLE',
     disabledTooltip: "This model is currently unavailable for your account.",
-    customModelPlaceholder: 'Custom model name',
-    customModelHint: 'Enter to load',
+    customModelPlaceholder: 'Unlisted model ID',
+    customModelHint: 'For provider-supported models not returned by the API; not a display rename. Press Enter to load.',
+    removeCustomModel: 'Remove this unlisted model',
     noProviders: 'No providers found. Add a custom provider to get started.',
     models: 'Models',
     count: 'models',
diff --git a/packages/client/src/i18n/locales/zh.ts b/packages/client/src/i18n/locales/zh.ts
index 4dc728d2..8d1c493a 100644
--- a/packages/client/src/i18n/locales/zh.ts
+++ b/packages/client/src/i18n/locales/zh.ts
@@ -547,8 +547,9 @@ export default {
     previewBadge: '预览',
     disabledBadge: '不可用',
     disabledTooltip: "此模型当前账号不可用",
-    customModelPlaceholder: '自定义模型名称',
-    customModelHint: '按回车加载',
+    customModelPlaceholder: '未列出的模型 ID',
+    customModelHint: '仅用于 provider 支持但未返回的模型；不是重命名。按回车加载。',
+    removeCustomModel: '移除这个未列出的模型',
     noProviders: '暂无 Provider，添加一个开始吧。',
     models: '模型列表',
     count: '个模型',
diff --git a/packages/client/src/stores/hermes/app.ts b/packages/client/src/stores/hermes/app.ts
index f5091520..da346ea3 100644
--- a/packages/client/src/stores/hermes/app.ts
+++ b/packages/client/src/stores/hermes/app.ts
@@ -119,6 +119,28 @@ export const useAppStore = defineStore('app', () => {
     }
   }
 
+  async function removeCustomModel(modelId: string, provider: string) {
+    const providerModels = customModels.value[provider] || []
+    if (!providerModels.includes(modelId)) return
+
+    const nextCustomModels = { ...customModels.value }
+    const remaining = providerModels.filter(m => m !== modelId)
+    if (remaining.length > 0) nextCustomModels[provider] = remaining
+    else delete nextCustomModels[provider]
+    customModels.value = nextCustomModels
+
+    if (selectedModel.value === modelId && selectedProvider.value === provider) {
+      const providerGroup = modelGroups.value.find(g => g.provider === provider && g.models.length > 0)
+      const fallbackGroup = providerGroup || modelGroups.value.find(g => g.models.length > 0)
+      if (fallbackGroup) {
+        await switchModel(fallbackGroup.models[0], fallbackGroup.provider)
+      } else {
+        selectedModel.value = ''
+        selectedProvider.value = ''
+      }
+    }
+  }
+
   function startHealthPolling(interval = 30000) {
     stopHealthPolling()
     checkConnection()
@@ -173,6 +195,7 @@ export const useAppStore = defineStore('app', () => {
     checkConnection,
     loadModels,
     switchModel,
+    removeCustomModel,
     getModelAlias,
     displayModelName,
     setModelAlias,
diff --git a/tests/client/app-store.test.ts b/tests/client/app-store.test.ts
index dcd32953..ab1ba1c5 100644
--- a/tests/client/app-store.test.ts
+++ b/tests/client/app-store.test.ts
@@ -90,4 +90,28 @@ describe('App Store', () => {
     await store.setModelAlias('deepseek-v4-flash', 'deepseek', '')
     expect(store.modelAliases).toEqual({})
   })
+
+  it('removes an unlisted custom model and falls back to a listed model when active', async () => {
+    mockSystemApi.updateDefaultModel.mockResolvedValue(undefined)
+    const store = useAppStore()
+    store.modelGroups = [{
+      provider: 'deepseek',
+      label: 'DeepSeek',
+      base_url: 'https://api.deepseek.com/v1',
+      models: ['deepseek-v4-flash'],
+      api_key: '',
+    }]
+
+    await store.switchModel('test', 'deepseek')
+    expect(store.selectedModel).toBe('test')
+    expect(store.customModels).toEqual({ deepseek: ['test'] })
+
+    await store.removeCustomModel('test', 'deepseek')
+    expect(store.customModels).toEqual({})
+    expect(store.selectedModel).toBe('deepseek-v4-flash')
+    expect(mockSystemApi.updateDefaultModel).toHaveBeenLastCalledWith({
+      default: 'deepseek-v4-flash',
+      provider: 'deepseek',
+    })
+  })
 })

From 9827e08d88af36a5ad457bed5a2aa29a9ea383f9 Mon Sep 17 00:00:00 2001
From: Zhicheng Han <zhicheng.han@mathematik.uni-goettingen.de>
Date: Sun, 10 May 2026 21:07:34 +0200
Subject: [PATCH 4/4] fix(models): scope aliases to providers

---
 packages/client/src/i18n/locales/de.ts   |  4 +-
 packages/client/src/i18n/locales/es.ts   |  4 +-
 packages/client/src/i18n/locales/fr.ts   |  4 +-
 packages/client/src/i18n/locales/ja.ts   |  4 +-
 packages/client/src/i18n/locales/ko.ts   |  4 +-
 packages/client/src/i18n/locales/pt.ts   |  4 +-
 packages/client/src/stores/hermes/app.ts | 11 ++++-
 tests/client/app-store.test.ts           | 56 ++++++++++++++++++++++++
 8 files changed, 78 insertions(+), 13 deletions(-)

diff --git a/packages/client/src/i18n/locales/de.ts b/packages/client/src/i18n/locales/de.ts
index b9eb4b3f..a0956f76 100644
--- a/packages/client/src/i18n/locales/de.ts
+++ b/packages/client/src/i18n/locales/de.ts
@@ -419,8 +419,8 @@ jobTriggered: 'Job ausgelost',
     previewBadge: 'VORSCHAU',
     disabledBadge: 'NICHT VERFÜGBAR',
     disabledTooltip: "Dieses Modell ist für Ihr Konto derzeit nicht verfügbar.",
-    customModelPlaceholder: 'Benutzerdefinierter Modellname',
-    customModelHint: 'Enter zum Laden',
+    customModelPlaceholder: 'Nicht gelistete Modell-ID',
+    customModelHint: 'Für vom Provider unterstützte Modelle, die die API nicht zurückgibt; keine Anzeige-Umbenennung. Enter zum Laden.',
     noProviders: 'Keine Anbieter gefunden. Fugen Sie einen benutzerdefinierten Anbieter hinzu, um zu beginnen.',
     builtIn: 'Integriert',
     customType: 'Benutzerdefiniert',
diff --git a/packages/client/src/i18n/locales/es.ts b/packages/client/src/i18n/locales/es.ts
index dcd3f513..d0d3fe39 100644
--- a/packages/client/src/i18n/locales/es.ts
+++ b/packages/client/src/i18n/locales/es.ts
@@ -419,8 +419,8 @@ jobTriggered: 'Job ejecutado',
     previewBadge: 'VISTA PREVIA',
     disabledBadge: 'NO DISPONIBLE',
     disabledTooltip: "Este modelo no está disponible para tu cuenta.",
-    customModelPlaceholder: 'Nombre del modelo personalizado',
-    customModelHint: 'Enter para cargar',
+    customModelPlaceholder: 'ID de modelo no listado',
+    customModelHint: 'Para modelos compatibles con el proveedor que la API no devuelve; no es un cambio de nombre visible. Enter para cargar.',
     noProviders: 'No se encontraron proveedores. Anade un proveedor personalizado para comenzar.',
     builtIn: 'Integrado',
     customType: 'Personalizado',
diff --git a/packages/client/src/i18n/locales/fr.ts b/packages/client/src/i18n/locales/fr.ts
index 263cd31e..6b18ce6d 100644
--- a/packages/client/src/i18n/locales/fr.ts
+++ b/packages/client/src/i18n/locales/fr.ts
@@ -419,8 +419,8 @@ jobTriggered: 'Job declenche',
     previewBadge: 'APERÇU',
     disabledBadge: 'INDISPONIBLE',
     disabledTooltip: "Ce modèle n'est pas disponible pour votre compte.",
-    customModelPlaceholder: 'Nom du modèle personnalisé',
-    customModelHint: 'Entrée pour charger',
+    customModelPlaceholder: 'ID de modèle non listé',
+    customModelHint: 'Pour les modèles pris en charge par le fournisseur mais non renvoyés par l’API ; ce n’est pas un renommage affiché. Entrée pour charger.',
     noProviders: 'Aucun fournisseur trouve. Ajoutez un fournisseur personnalise pour commencer.',
     builtIn: 'Integre',
     customType: 'Personnalise',
diff --git a/packages/client/src/i18n/locales/ja.ts b/packages/client/src/i18n/locales/ja.ts
index 46020ff8..d9045fcc 100644
--- a/packages/client/src/i18n/locales/ja.ts
+++ b/packages/client/src/i18n/locales/ja.ts
@@ -419,8 +419,8 @@ export default {
     previewBadge: 'プレビュー',
     disabledBadge: '利用不可',
     disabledTooltip: "このモデルは現在のアカウントでは利用できません。",
-    customModelPlaceholder: 'カスタムモデル名',
-    customModelHint: 'Enterで読み込み',
+    customModelPlaceholder: '未掲載のモデル ID',
+    customModelHint: 'プロバイダーは対応しているが API が返さないモデル用です。表示名の変更ではありません。Enter で読み込み。',
     noProviders: 'プロバイダーがありません。カスタムプロバイダーを追加して始めましょう。',
     builtIn: '組み込み',
     customType: 'カスタム',
diff --git a/packages/client/src/i18n/locales/ko.ts b/packages/client/src/i18n/locales/ko.ts
index b85f113c..d8315a44 100644
--- a/packages/client/src/i18n/locales/ko.ts
+++ b/packages/client/src/i18n/locales/ko.ts
@@ -419,8 +419,8 @@ export default {
     previewBadge: '프리뷰',
     disabledBadge: '사용 불가',
     disabledTooltip: "이 모델은 현재 계정에서 사용할 수 없습니다.",
-    customModelPlaceholder: '사용자 지정 모델 이름',
-    customModelHint: 'Enter로 불러오기',
+    customModelPlaceholder: '목록에 없는 모델 ID',
+    customModelHint: '제공자는 지원하지만 API가 반환하지 않는 모델용입니다. 표시 이름 변경이 아닙니다. Enter로 불러옵니다.',
     noProviders: 'Provider가 없습니다. 사용자 지정 Provider를 추가하여 시작하세요.',
     builtIn: '내장',
     customType: '사용자 지정',
diff --git a/packages/client/src/i18n/locales/pt.ts b/packages/client/src/i18n/locales/pt.ts
index 0c9a55b2..18f3bbf2 100644
--- a/packages/client/src/i18n/locales/pt.ts
+++ b/packages/client/src/i18n/locales/pt.ts
@@ -419,8 +419,8 @@ jobTriggered: 'Job acionado',
     previewBadge: 'PRÉVIA',
     disabledBadge: 'INDISPONÍVEL',
     disabledTooltip: "Este modelo não está disponível para sua conta.",
-    customModelPlaceholder: 'Nome do modelo personalizado',
-    customModelHint: 'Enter para carregar',
+    customModelPlaceholder: 'ID de modelo não listado',
+    customModelHint: 'Para modelos compatíveis com o provedor que a API não retorna; não é uma renomeação de exibição. Enter para carregar.',
     noProviders: 'Nenhum provedor encontrado. Adicione um provedor personalizado para comecar.',
     builtIn: 'Integrado',
     customType: 'Personalizado',
diff --git a/packages/client/src/stores/hermes/app.ts b/packages/client/src/stores/hermes/app.ts
index da346ea3..7e4957ea 100644
--- a/packages/client/src/stores/hermes/app.ts
+++ b/packages/client/src/stores/hermes/app.ts
@@ -66,13 +66,22 @@ export const useAppStore = defineStore('app', () => {
       modelAliases.value = res.model_aliases || {}
       selectedModel.value = res.default
       selectedProvider.value = res.default_provider || ''
+
+      const defaultProvider = res.default_provider || ''
+      if (defaultProvider && res.default) {
+        const providerGroup = res.groups.find(g => g.provider === defaultProvider)
+        const isListed = providerGroup?.models.includes(res.default) ?? false
+        customModels.value = isListed ? {} : { [defaultProvider]: [res.default] }
+      } else {
+        customModels.value = {}
+      }
     } catch {
       // ignore
     }
   }
 
   function getModelAlias(modelId: string, provider?: string): string {
-    if (provider && modelAliases.value[provider]?.[modelId]) return modelAliases.value[provider][modelId]
+    if (provider) return modelAliases.value[provider]?.[modelId] || ''
     for (const aliases of Object.values(modelAliases.value)) {
       if (aliases[modelId]) return aliases[modelId]
     }
diff --git a/tests/client/app-store.test.ts b/tests/client/app-store.test.ts
index ab1ba1c5..a02625e6 100644
--- a/tests/client/app-store.test.ts
+++ b/tests/client/app-store.test.ts
@@ -74,6 +74,62 @@ describe('App Store', () => {
     expect(store.displayModelName('unknown', 'deepseek')).toBe('unknown')
   })
 
+  it('keeps aliases scoped to their provider when model IDs overlap', async () => {
+    mockSystemApi.fetchAvailableModels.mockResolvedValue({
+      default: 'shared-model',
+      default_provider: 'provider-a',
+      groups: [
+        {
+          provider: 'provider-a',
+          label: 'Provider A',
+          base_url: 'https://a.example/v1',
+          models: ['shared-model'],
+          api_key: '',
+        },
+        {
+          provider: 'provider-b',
+          label: 'Provider B',
+          base_url: 'https://b.example/v1',
+          models: ['shared-model'],
+          api_key: '',
+        },
+      ],
+      allProviders: [],
+      model_aliases: {
+        'provider-a': { 'shared-model': 'A Alias' },
+      },
+    })
+    const store = useAppStore()
+
+    await store.loadModels()
+
+    expect(store.displayModelName('shared-model', 'provider-a')).toBe('A Alias')
+    expect(store.displayModelName('shared-model', 'provider-b')).toBe('shared-model')
+    expect(store.displayModelName('shared-model')).toBe('A Alias')
+  })
+
+  it('rehydrates an active unlisted default model as removable after loading models', async () => {
+    mockSystemApi.fetchAvailableModels.mockResolvedValue({
+      default: 'manually-supported-id',
+      default_provider: 'deepseek',
+      groups: [{
+        provider: 'deepseek',
+        label: 'DeepSeek',
+        base_url: 'https://api.deepseek.com/v1',
+        models: ['deepseek-v4-flash'],
+        api_key: '',
+      }],
+      allProviders: [],
+      model_aliases: {},
+    })
+    const store = useAppStore()
+
+    await store.loadModels()
+
+    expect(store.selectedModel).toBe('manually-supported-id')
+    expect(store.customModels).toEqual({ deepseek: ['manually-supported-id'] })
+  })
+
   it('saves and clears model aliases via the Web UI-only alias API', async () => {
     mockSystemApi.updateModelAlias.mockResolvedValue(undefined)
     const store = useAppStore()