From d8015b7defe7c9f71d49d08fd9e00761e7046338 Mon Sep 17 00:00:00 2001
From: jxxghp <jxxghp@gmail.com>
Date: Tue, 16 Jun 2026 20:44:00 +0800
Subject: [PATCH] feat: add Agent Assistant component and integrate with theme
 customizer

- Implemented Agent Assistant widget with chat functionality, including message handling and streaming responses.
- Added new localization strings for Agent Assistant in English, Simplified Chinese, and Traditional Chinese.
- Updated DefaultLayout to include the Agent Assistant and Theme Customizer components.
- Enhanced UserProfile to manage the opening of the Theme Customizer through global events.
- Adjusted CSS styles for the Agent Assistant and its interactions with other components.
- Introduced new events for opening the Theme Customizer and managing its state.
---
 src/components/AgentAssistantWidget.vue   | 1035 +++++++++++++++++++++
 src/components/ThemeCustomizer.vue        |  569 +++++------
 src/components/dialog/CustomCssDialog.vue |    6 +-
 src/composables/useThemeCustomizer.ts     |    1 +
 src/layouts/components/DefaultLayout.vue  |   25 +-
 src/layouts/components/UserProfile.vue    |   15 +-
 src/locales/en-US.ts                      |   13 +
 src/locales/zh-CN.ts                      |   13 +
 src/locales/zh-TW.ts                      |   13 +
 src/styles/common.scss                    |   15 +
 10 files changed, 1340 insertions(+), 365 deletions(-)
 create mode 100644 src/components/AgentAssistantWidget.vue

diff --git a/src/components/AgentAssistantWidget.vue b/src/components/AgentAssistantWidget.vue
new file mode 100644
index 00000000..361007ca
--- /dev/null
+++ b/src/components/AgentAssistantWidget.vue
@@ -0,0 +1,1035 @@
+<script setup lang="ts">
+import MarkdownIt from 'markdown-it'
+import mdLinkAttributes from 'markdown-it-link-attributes'
+import { useDisplay } from 'vuetify'
+import { useI18n } from 'vue-i18n'
+import { useAuthStore, useUserStore } from '@/stores'
+
+type AgentMessageRole = 'user' | 'assistant'
+type AgentMessageStatus = 'idle' | 'streaming' | 'done' | 'error'
+type AgentAttachmentKind = 'audio' | 'file' | 'image'
+
+interface AgentToolCall {
+  id: string
+  message: string
+  status: 'running' | 'done'
+}
+
+interface AgentMessageAttachment {
+  kind: AgentAttachmentKind
+  url: string
+  download_url?: string
+  name?: string
+  mime_type?: string
+  size?: number
+}
+
+interface AgentChatMessage {
+  id: string
+  role: AgentMessageRole
+  content: string
+  createdAt: number
+  status: AgentMessageStatus
+  tools: AgentToolCall[]
+  attachments: AgentMessageAttachment[]
+}
+
+interface AgentStreamEvent {
+  type: 'start' | 'delta' | 'tool' | 'attachment' | 'done' | 'error'
+  attachment?: AgentMessageAttachment
+  content?: string
+  message?: string
+  session_id?: string
+}
+
+const { t } = useI18n()
+const display = useDisplay()
+const authStore = useAuthStore()
+const userStore = useUserStore()
+
+const STORAGE_KEY = 'moviepilot-agent-assistant-state'
+const MAX_PERSISTED_MESSAGES = 30
+
+const drawer = ref(false)
+const drawerViewportHeight = ref('100dvh')
+const inputText = ref('')
+const messages = ref<AgentChatMessage[]>([])
+const sessionId = ref('')
+const sending = ref(false)
+const streamError = ref('')
+const messageListRef = ref<HTMLElement | null>(null)
+const inputRef = ref<HTMLTextAreaElement | null>(null)
+let abortController: AbortController | null = null
+
+const md = new MarkdownIt({
+  html: false,
+  breaks: true,
+  linkify: true,
+  typographer: true,
+})
+
+md.use(mdLinkAttributes, {
+  attrs: {
+    target: '_blank',
+    rel: 'noopener noreferrer',
+  },
+})
+
+const canSend = computed(() => inputText.value.trim().length > 0 && !sending.value)
+// 窄屏下直接全屏，避免聊天内容被压成半屏窄栏。
+const drawerWidth = computed(() => (display.mdAndDown.value ? '100vw' : '30rem'))
+const hasMessages = computed(() => messages.value.length > 0)
+const currentUserName = computed(() => userStore.getUserName || t('common.user'))
+const drawerStyle = computed(() => ({
+  '--agent-assistant-viewport-height': drawerViewportHeight.value,
+  '--agent-assistant-panel-width': drawerWidth.value,
+}))
+
+function createId(prefix: string) {
+  return `${prefix}-${Date.now()}-${Math.random().toString(16).slice(2)}`
+}
+
+function createSessionId() {
+  return `web-${Date.now()}-${Math.random().toString(16).slice(2)}`
+}
+
+function normalizeStoredMessages(value: unknown) {
+  if (!Array.isArray(value)) return []
+
+  return value.slice(-MAX_PERSISTED_MESSAGES).map(message => ({
+    ...message,
+    attachments: Array.isArray(message.attachments) ? message.attachments : [],
+    tools: Array.isArray(message.tools) ? message.tools : [],
+  })) as AgentChatMessage[]
+}
+
+function restoreState() {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY)
+    if (!raw) {
+      sessionId.value = createSessionId()
+      return
+    }
+
+    const state = JSON.parse(raw)
+    sessionId.value = state.sessionId || createSessionId()
+    messages.value = normalizeStoredMessages(state.messages)
+  } catch (error) {
+    sessionId.value = createSessionId()
+  }
+}
+
+function persistState() {
+  localStorage.setItem(
+    STORAGE_KEY,
+    JSON.stringify({
+      sessionId: sessionId.value,
+      messages: messages.value.slice(-MAX_PERSISTED_MESSAGES),
+    }),
+  )
+}
+
+function renderMarkdown(value: string) {
+  if (!value) return ''
+  return md.render(value)
+}
+
+function resolveApiUrl(path: string) {
+  const baseUrl = import.meta.env.VITE_API_BASE_URL || '/'
+  return `${baseUrl.replace(/\/?$/, '/')}${path.replace(/^\//, '')}`
+}
+
+function scrollToBottom() {
+  nextTick(() => {
+    requestAnimationFrame(() => {
+      if (!messageListRef.value) return
+      messageListRef.value.scrollTop = messageListRef.value.scrollHeight
+    })
+  })
+}
+
+function syncInputHeight() {
+  nextTick(() => {
+    const input = inputRef.value
+    if (!input) return
+
+    input.style.blockSize = 'auto'
+    input.style.blockSize = `${Math.min(input.scrollHeight, 120)}px`
+  })
+}
+
+function addMessage(role: AgentMessageRole, content: string, status: AgentMessageStatus = 'idle') {
+  const message: AgentChatMessage = {
+    id: createId(role),
+    role,
+    content,
+    createdAt: Date.now(),
+    status,
+    attachments: [],
+    tools: [],
+  }
+  messages.value.push(message)
+  persistState()
+  scrollToBottom()
+  return message
+}
+
+function normalizeToolMessage(message: string) {
+  return message.replace(/^=>\s*/, '').trim()
+}
+
+function markToolsDone(message: AgentChatMessage) {
+  message.tools.forEach(tool => {
+    tool.status = 'done'
+  })
+}
+
+function applyStreamEvent(event: AgentStreamEvent, assistantMessage: AgentChatMessage) {
+  switch (event.type) {
+    case 'delta':
+      assistantMessage.content += event.content || ''
+      break
+    case 'tool':
+      markToolsDone(assistantMessage)
+      assistantMessage.tools.push({
+        id: createId('tool'),
+        message: normalizeToolMessage(event.message || ''),
+        status: 'running',
+      })
+      break
+    case 'attachment':
+      if (event.attachment?.url) {
+        assistantMessage.attachments.push(event.attachment)
+      }
+      break
+    case 'done':
+      if (assistantMessage.status !== 'error') {
+        assistantMessage.status = 'done'
+      }
+      markToolsDone(assistantMessage)
+      break
+    case 'error':
+      assistantMessage.status = 'error'
+      streamError.value = event.message || t('agentAssistant.error')
+      if (!assistantMessage.content) assistantMessage.content = streamError.value
+      markToolsDone(assistantMessage)
+      break
+    case 'start':
+    default:
+      break
+  }
+
+  persistState()
+  scrollToBottom()
+}
+
+function parseSseBlock(block: string) {
+  const data = block
+    .split('\n')
+    .filter(line => line.startsWith('data:'))
+    .map(line => line.slice(5).trimStart())
+    .join('\n')
+
+  if (!data) return null
+  return JSON.parse(data) as AgentStreamEvent
+}
+
+async function readAgentStream(response: Response, assistantMessage: AgentChatMessage) {
+  if (!response.body) {
+    throw new Error(t('agentAssistant.noStream'))
+  }
+
+  const reader = response.body.getReader()
+  const decoder = new TextDecoder('utf-8')
+  let buffer = ''
+
+  while (true) {
+    const { value, done } = await reader.read()
+    if (done) break
+
+    buffer += decoder.decode(value, { stream: true })
+    const blocks = buffer.split(/\n\n/)
+    buffer = blocks.pop() || ''
+
+    for (const block of blocks) {
+      const event = parseSseBlock(block)
+      if (event) applyStreamEvent(event, assistantMessage)
+    }
+  }
+
+  buffer += decoder.decode()
+  if (buffer.trim()) {
+    const event = parseSseBlock(buffer)
+    if (event) applyStreamEvent(event, assistantMessage)
+  }
+}
+
+function resolveAttachmentUrl(url?: string) {
+  if (!url) return ''
+  if (/^(https?:|data:|blob:|\/)/.test(url)) return url
+
+  return resolveApiUrl(url)
+}
+
+function getAttachmentDownloadUrl(attachment: AgentMessageAttachment) {
+  return resolveAttachmentUrl(attachment.download_url || attachment.url)
+}
+
+function getAttachmentName(attachment: AgentMessageAttachment) {
+  return attachment.name || (attachment.kind === 'image' ? 'image' : 'attachment')
+}
+
+function getAttachmentIcon(attachment: AgentMessageAttachment) {
+  if (attachment.kind === 'audio') return 'mdi-volume-high'
+  if (attachment.kind === 'image') return 'mdi-image-outline'
+  return 'mdi-file-outline'
+}
+
+function formatAttachmentSize(size?: number) {
+  if (!size) return ''
+  if (size < 1024) return `${size} B`
+  if (size < 1024 * 1024) return `${(size / 1024).toFixed(1)} KB`
+  return `${(size / 1024 / 1024).toFixed(1)} MB`
+}
+
+function getVisibleViewportHeight() {
+  if (typeof window === 'undefined') return '100dvh'
+
+  const height = window.visualViewport?.height || window.innerHeight || document.documentElement.clientHeight
+
+  return height > 0 ? `${Math.round(height)}px` : '100dvh'
+}
+
+// iOS 独立模式和地址栏收起时可见高度会变化，抽屉需要跟随真实 viewport。
+function syncDrawerViewportHeight() {
+  drawerViewportHeight.value = getVisibleViewportHeight()
+}
+
+async function sendMessage() {
+  const text = inputText.value.trim()
+  if (!text || sending.value) return
+
+  streamError.value = ''
+  inputText.value = ''
+  syncInputHeight()
+  addMessage('user', text, 'done')
+  const assistantMessage = addMessage('assistant', '', 'streaming')
+
+  abortController = new AbortController()
+  sending.value = true
+
+  try {
+    const response = await fetch(resolveApiUrl('message/agent/stream'), {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...(authStore.token ? { Authorization: `Bearer ${authStore.token}` } : {}),
+      },
+      body: JSON.stringify({
+        text,
+        session_id: sessionId.value,
+      }),
+      credentials: 'include',
+      signal: abortController.signal,
+    })
+
+    if (!response.ok) {
+      throw new Error(`${response.status} ${response.statusText}`.trim())
+    }
+
+    await readAgentStream(response, assistantMessage)
+    if (assistantMessage.status === 'streaming') {
+      assistantMessage.status = 'done'
+      markToolsDone(assistantMessage)
+    }
+  } catch (error: any) {
+    if (error?.name === 'AbortError') {
+      assistantMessage.status = 'done'
+      markToolsDone(assistantMessage)
+      return
+    }
+
+    assistantMessage.status = 'error'
+    assistantMessage.content = error?.message || t('agentAssistant.error')
+    streamError.value = assistantMessage.content
+    markToolsDone(assistantMessage)
+  } finally {
+    sending.value = false
+    abortController = null
+    persistState()
+    scrollToBottom()
+  }
+}
+
+function stopGeneration() {
+  abortController?.abort()
+}
+
+function startNewSession() {
+  stopGeneration()
+  sessionId.value = createSessionId()
+  messages.value = []
+  streamError.value = ''
+  persistState()
+}
+
+function openDrawer() {
+  drawer.value = true
+  scrollToBottom()
+}
+
+function closeDrawer() {
+  drawer.value = false
+}
+
+function syncAgentAssistantOpenState(isOpen: boolean) {
+  if (typeof document === 'undefined') return
+
+  const roots = [document.documentElement, document.body]
+  roots.forEach(root => {
+    if (isOpen) {
+      root.setAttribute('data-agent-assistant-open', 'true')
+      return
+    }
+
+    root.removeAttribute('data-agent-assistant-open')
+  })
+
+  if (isOpen) {
+    document.documentElement.style.setProperty('--agent-assistant-fab-offset', drawerWidth.value)
+  } else {
+    document.documentElement.style.removeProperty('--agent-assistant-fab-offset')
+  }
+}
+
+function clearAgentAssistantOpenState() {
+  syncAgentAssistantOpenState(false)
+}
+
+function handleGlobalKeydown(event: KeyboardEvent) {
+  if (event.key === 'Escape' && drawer.value) closeDrawer()
+}
+
+function handleInputKeydown(event: KeyboardEvent) {
+  if (event.key !== 'Enter' || event.shiftKey) return
+  event.preventDefault()
+  sendMessage()
+}
+
+watch(drawer, syncAgentAssistantOpenState, { immediate: true })
+watch(drawerWidth, () => {
+  if (drawer.value) syncAgentAssistantOpenState(true)
+})
+
+onMounted(() => {
+  restoreState()
+  syncDrawerViewportHeight()
+  syncInputHeight()
+  window.addEventListener('resize', syncDrawerViewportHeight)
+  window.addEventListener('orientationchange', syncDrawerViewportHeight)
+  window.addEventListener('keydown', handleGlobalKeydown)
+  window.visualViewport?.addEventListener('resize', syncDrawerViewportHeight)
+  window.visualViewport?.addEventListener('scroll', syncDrawerViewportHeight)
+})
+
+onScopeDispose(clearAgentAssistantOpenState)
+onScopeDispose(() => {
+  if (typeof window === 'undefined') return
+
+  window.removeEventListener('resize', syncDrawerViewportHeight)
+  window.removeEventListener('orientationchange', syncDrawerViewportHeight)
+  window.removeEventListener('keydown', handleGlobalKeydown)
+  window.visualViewport?.removeEventListener('resize', syncDrawerViewportHeight)
+  window.visualViewport?.removeEventListener('scroll', syncDrawerViewportHeight)
+})
+</script>
+
+<template>
+  <button
+    v-if="!drawer"
+    class="agent-assistant-fab"
+    type="button"
+    :aria-label="t('agentAssistant.title')"
+    :title="t('agentAssistant.title')"
+    @click="openDrawer"
+  >
+    <VIcon icon="lucide:bot" size="21" />
+  </button>
+
+  <aside
+    v-show="drawer"
+    class="agent-assistant-panel"
+    :style="drawerStyle"
+    role="dialog"
+    :aria-label="t('agentAssistant.title')"
+  >
+    <div class="agent-assistant-shell">
+      <header class="agent-assistant-header">
+        <div class="agent-assistant-title">
+          <div class="agent-assistant-title__mark">
+            <VIcon icon="lucide:bot" size="22" />
+          </div>
+          <div>
+            <div class="text-subtitle-1 font-weight-semibold">{{ t('agentAssistant.title') }}</div>
+            <div class="agent-assistant-status">
+              {{ sending ? t('agentAssistant.thinking') : t('agentAssistant.ready') }}
+            </div>
+          </div>
+        </div>
+        <div class="d-flex align-center gap-1">
+          <IconBtn
+            :disabled="sending"
+            :title="t('agentAssistant.newChat')"
+            :aria-label="t('agentAssistant.newChat')"
+            @click="startNewSession"
+          >
+            <VIcon icon="mdi-message-plus-outline" />
+          </IconBtn>
+          <IconBtn :title="t('common.close')" :aria-label="t('common.close')" @click="closeDrawer">
+            <VIcon icon="mdi-close" />
+          </IconBtn>
+        </div>
+      </header>
+
+      <main ref="messageListRef" class="agent-assistant-messages">
+        <div v-if="!hasMessages" class="agent-assistant-empty">
+          <VIcon icon="mdi-creation-outline" size="34" />
+          <div class="text-subtitle-2 mt-3">{{ t('agentAssistant.emptyTitle') }}</div>
+        </div>
+
+        <div
+          v-for="message in messages"
+          :key="message.id"
+          class="agent-assistant-message"
+          :class="`agent-assistant-message--${message.role}`"
+        >
+          <div class="agent-assistant-message__meta">
+            <VIcon :icon="message.role === 'user' ? 'mdi-account-circle-outline' : 'lucide:bot'" size="16" />
+            <span>{{ message.role === 'user' ? currentUserName : t('agentAssistant.assistant') }}</span>
+          </div>
+
+          <div v-if="message.tools.length" class="agent-assistant-tools">
+            <div v-for="tool in message.tools" :key="tool.id" class="agent-assistant-tool">
+              <VIcon
+                :icon="
+                  tool.status === 'running' && message.status === 'streaming'
+                    ? 'line-md:loading-twotone-loop'
+                    : 'mdi-check-circle-outline'
+                "
+                size="16"
+              />
+              <span>{{ tool.message }}</span>
+            </div>
+          </div>
+
+          <div
+            v-if="message.content"
+            class="agent-assistant-message__bubble markdown-body"
+            v-html="renderMarkdown(message.content)"
+          />
+
+          <div v-if="message.attachments.length" class="agent-assistant-attachments">
+            <div
+              v-for="attachment in message.attachments"
+              :key="`${message.id}-${attachment.url}`"
+              class="agent-assistant-attachment"
+              :class="`agent-assistant-attachment--${attachment.kind}`"
+            >
+              <img
+                v-if="attachment.kind === 'image'"
+                class="agent-assistant-attachment__image"
+                :src="resolveAttachmentUrl(attachment.url)"
+                :alt="getAttachmentName(attachment)"
+                loading="lazy"
+              />
+
+              <template v-else-if="attachment.kind === 'audio'">
+                <div class="agent-assistant-attachment__meta">
+                  <VIcon :icon="getAttachmentIcon(attachment)" size="18" />
+                  <span>{{ getAttachmentName(attachment) }}</span>
+                </div>
+                <audio class="agent-assistant-attachment__audio" controls :src="resolveAttachmentUrl(attachment.url)" />
+                <VBtn
+                  :href="getAttachmentDownloadUrl(attachment)"
+                  :download="getAttachmentName(attachment)"
+                  size="small"
+                  variant="tonal"
+                  color="primary"
+                  prepend-icon="mdi-download"
+                >
+                  {{ t('agentAssistant.download') }}
+                </VBtn>
+              </template>
+
+              <template v-else>
+                <div class="agent-assistant-attachment__file">
+                  <VIcon :icon="getAttachmentIcon(attachment)" size="22" />
+                  <div class="agent-assistant-attachment__file-text">
+                    <span>{{ getAttachmentName(attachment) }}</span>
+                    <small>{{ attachment.mime_type || formatAttachmentSize(attachment.size) }}</small>
+                  </div>
+                  <VBtn
+                    :href="getAttachmentDownloadUrl(attachment)"
+                    :download="getAttachmentName(attachment)"
+                    icon
+                    variant="text"
+                    color="primary"
+                    :aria-label="t('agentAssistant.download')"
+                  >
+                    <VIcon icon="mdi-download" />
+                  </VBtn>
+                </div>
+              </template>
+            </div>
+          </div>
+
+          <div
+            v-if="!message.content && !message.attachments.length && message.status === 'streaming'"
+            class="agent-assistant-typing"
+          >
+            <span />
+            <span />
+            <span />
+          </div>
+        </div>
+      </main>
+
+      <footer class="agent-assistant-composer">
+        <VAlert v-if="streamError" type="error" variant="tonal" density="compact" class="mb-3">
+          {{ streamError }}
+        </VAlert>
+        <div class="agent-assistant-input">
+          <textarea
+            ref="inputRef"
+            v-model="inputText"
+            class="agent-assistant-textarea"
+            rows="1"
+            :disabled="sending"
+            :placeholder="t('agentAssistant.placeholder')"
+            @input="syncInputHeight"
+            @keydown="handleInputKeydown"
+          />
+          <IconBtn
+            class="agent-assistant-send"
+            :disabled="!sending && !canSend"
+            :title="sending ? t('agentAssistant.stop') : t('common.send')"
+            :aria-label="sending ? t('agentAssistant.stop') : t('common.send')"
+            @click="sending ? stopGeneration() : sendMessage()"
+          >
+            <VIcon :icon="sending ? 'mdi-stop' : 'mdi-send'" />
+          </IconBtn>
+        </div>
+      </footer>
+    </div>
+  </aside>
+</template>
+
+<style lang="scss" scoped>
+/* stylelint-disable selector-pseudo-class-no-unknown */
+/* stylelint-disable no-descending-specificity */
+
+.agent-assistant-fab {
+  position: fixed;
+  z-index: 2100;
+  display: grid;
+  border: 1px solid rgba(var(--v-theme-on-surface), 0.08);
+  border-radius: 999px 0 0 999px;
+  backdrop-filter: blur(10px);
+  background: rgba(var(--v-theme-surface), 0.86);
+  block-size: 2.5rem;
+  border-inline-end: 0;
+  box-shadow: var(--app-surface-shadow);
+  color: rgb(var(--v-theme-primary));
+  inline-size: 2.8rem;
+  inset-block-start: 50%;
+  inset-inline-end: 0;
+  place-items: center;
+  transform: translate(1.35rem, -50%);
+  transition:
+    inset-inline-end 0.2s ease,
+    transform 0.18s ease,
+    box-shadow 0.18s ease;
+}
+
+.agent-assistant-fab:hover {
+  box-shadow: var(--app-surface-hover-shadow);
+  transform: translate(0, -50%);
+}
+
+.agent-assistant-panel {
+  position: fixed;
+  z-index: 2101;
+  overflow: hidden;
+  background: rgb(var(--v-theme-surface));
+  block-size: var(--agent-assistant-viewport-height, 100dvh) !important;
+  border-inline-start: 1px solid rgba(var(--v-border-color), var(--v-border-opacity));
+  box-shadow: var(--app-surface-shadow);
+  inline-size: var(--agent-assistant-panel-width, 30rem);
+  inset-block-start: 0;
+  inset-inline-end: 0;
+  max-block-size: var(--agent-assistant-viewport-height, 100dvh) !important;
+}
+
+.agent-assistant-shell {
+  position: relative;
+  display: grid;
+  block-size: 100%;
+  grid-template-rows: auto 1fr;
+  min-block-size: 0;
+
+  --agent-assistant-assistant-bg: rgba(var(--v-theme-surface), 0.92);
+  --agent-assistant-assistant-border: rgba(var(--v-theme-on-surface), 0.08);
+  --agent-assistant-panel-bg: rgba(var(--v-theme-surface), 0.94);
+  --agent-assistant-panel-blur: 10px;
+}
+
+.agent-assistant-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  border-block-end: 1px solid rgba(var(--v-border-color), var(--v-border-opacity));
+  padding-block: calc(env(safe-area-inset-top, 0px) + 0.8rem) 0.8rem;
+  padding-inline: 1rem;
+}
+
+.agent-assistant-title {
+  display: flex;
+  align-items: center;
+  column-gap: 0.75rem;
+  min-inline-size: 0;
+}
+
+.agent-assistant-title__mark {
+  display: inline-flex;
+  flex: 0 0 auto;
+  align-items: center;
+  justify-content: center;
+  border-radius: 12px;
+  background: rgba(var(--v-theme-primary), 0.12);
+  block-size: 2.5rem;
+  color: rgb(var(--v-theme-primary));
+  inline-size: 2.5rem;
+}
+
+.agent-assistant-status {
+  color: rgba(var(--v-theme-on-surface), 0.62);
+  font-size: 0.78rem;
+}
+
+.agent-assistant-messages {
+  overflow-y: auto;
+  padding-block: 1rem calc(env(safe-area-inset-bottom, 0px) + 8.4rem);
+  padding-inline: 1rem;
+  scrollbar-width: thin;
+}
+
+.agent-assistant-empty {
+  display: grid;
+  color: rgba(var(--v-theme-on-surface), 0.58);
+  min-block-size: 55%;
+  place-content: center;
+  text-align: center;
+}
+
+.agent-assistant-message {
+  display: flex;
+  flex-direction: column;
+  margin-block-end: 1rem;
+}
+
+.agent-assistant-message--user {
+  align-items: flex-end;
+}
+
+.agent-assistant-message--assistant {
+  align-items: flex-start;
+}
+
+.agent-assistant-message__meta {
+  display: inline-flex;
+  align-items: center;
+  color: rgba(var(--v-theme-on-surface), 0.56);
+  column-gap: 0.3rem;
+  font-size: 0.75rem;
+  margin-block-end: 0.35rem;
+}
+
+.agent-assistant-message__bubble {
+  border: 1px solid rgba(var(--v-border-color), var(--v-border-opacity));
+  border-radius: 16px;
+  max-inline-size: min(100%, 34rem);
+  padding-block: 0.75rem;
+  padding-inline: 0.85rem;
+}
+
+.agent-assistant-message--user .agent-assistant-message__bubble {
+  border-color: rgba(var(--v-theme-primary), 0.18);
+  background: rgba(var(--v-theme-primary), 0.12);
+}
+
+.agent-assistant-message--assistant .agent-assistant-message__bubble {
+  border-color: var(--agent-assistant-assistant-border);
+  backdrop-filter: blur(var(--agent-assistant-panel-blur));
+  background: var(--agent-assistant-assistant-bg);
+}
+
+.agent-assistant-tools {
+  display: grid;
+  gap: 0.4rem;
+  inline-size: min(100%, 34rem);
+  margin-block-end: 0.5rem;
+}
+
+.agent-assistant-tool {
+  display: flex;
+  align-items: center;
+  border: 1px solid rgba(25, 178, 160, 28%);
+  border-radius: 10px;
+  background: rgba(25, 178, 160, 8%);
+  color: rgba(var(--v-theme-on-surface), 0.78);
+  column-gap: 0.45rem;
+  font-size: 0.8rem;
+  line-height: 1.35;
+  padding-block: 0.45rem;
+  padding-inline: 0.6rem;
+}
+
+.agent-assistant-typing {
+  display: inline-flex;
+  border: 1px solid var(--agent-assistant-assistant-border);
+  border-radius: 999px;
+  backdrop-filter: blur(var(--agent-assistant-panel-blur));
+  background: var(--agent-assistant-assistant-bg);
+  gap: 0.28rem;
+  padding-block: 0.7rem;
+  padding-inline: 0.8rem;
+}
+
+.agent-assistant-typing span {
+  border-radius: 999px;
+  animation: agent-typing 1s infinite ease-in-out;
+  background: rgba(var(--v-theme-on-surface), 0.54);
+  block-size: 0.35rem;
+  inline-size: 0.35rem;
+}
+
+.agent-assistant-typing span:nth-child(2) {
+  animation-delay: 0.15s;
+}
+
+.agent-assistant-typing span:nth-child(3) {
+  animation-delay: 0.3s;
+}
+
+.agent-assistant-composer {
+  position: absolute;
+  z-index: 2;
+  inset-block-end: calc(env(safe-area-inset-bottom, 0px) + 0.85rem);
+  inset-inline: 1rem;
+  pointer-events: none;
+}
+
+.agent-assistant-composer > * {
+  pointer-events: auto;
+}
+
+.agent-assistant-input {
+  display: grid;
+  align-items: center;
+  border: 1px solid rgba(var(--v-theme-on-surface), 0.1);
+  border-radius: 16px;
+  backdrop-filter: blur(var(--agent-assistant-panel-blur));
+  background: var(--agent-assistant-panel-bg);
+  box-shadow: var(--app-surface-shadow);
+  grid-template-columns: 1fr auto;
+  min-block-size: 3.25rem;
+  padding-inline: 0.85rem 0.35rem;
+  pointer-events: auto;
+}
+
+.agent-assistant-textarea {
+  box-sizing: border-box;
+  align-self: center;
+  padding: 0;
+  border: 0;
+  background: transparent;
+  block-size: 1.5rem;
+  color: rgba(var(--v-theme-on-surface), var(--v-high-emphasis-opacity));
+  font: inherit;
+  inline-size: 100%;
+  line-height: 1.5rem;
+  max-block-size: 7.5rem;
+  min-block-size: 1.5rem;
+  outline: none;
+  overflow-y: auto;
+  resize: none;
+}
+
+.agent-assistant-textarea::placeholder {
+  color: rgba(var(--v-theme-on-surface), var(--v-medium-emphasis-opacity));
+  opacity: 1;
+}
+
+.agent-assistant-send {
+  align-self: center;
+}
+
+.agent-assistant-attachments {
+  display: grid;
+  gap: 0.55rem;
+  inline-size: min(100%, 34rem);
+  margin-block-start: 0.5rem;
+}
+
+.agent-assistant-attachment {
+  overflow: hidden;
+  border: 1px solid var(--agent-assistant-assistant-border);
+  border-radius: 14px;
+  backdrop-filter: blur(var(--agent-assistant-panel-blur));
+  background: var(--agent-assistant-assistant-bg);
+}
+
+.agent-assistant-attachment__image {
+  display: block;
+  block-size: auto;
+  inline-size: 100%;
+  max-block-size: 18rem;
+  object-fit: contain;
+}
+
+.agent-assistant-attachment--audio {
+  display: grid;
+  padding: 0.75rem;
+  gap: 0.65rem;
+}
+
+.agent-assistant-attachment__meta {
+  display: flex;
+  align-items: center;
+  color: rgba(var(--v-theme-on-surface), 0.76);
+  column-gap: 0.45rem;
+  font-size: 0.82rem;
+  min-inline-size: 0;
+}
+
+.agent-assistant-attachment__meta span {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.agent-assistant-attachment__audio {
+  inline-size: 100%;
+}
+
+.agent-assistant-attachment__file {
+  display: grid;
+  align-items: center;
+  column-gap: 0.65rem;
+  grid-template-columns: auto 1fr auto;
+  min-inline-size: 0;
+  padding-block: 0.65rem;
+  padding-inline: 0.75rem 0.45rem;
+}
+
+.agent-assistant-attachment__file-text {
+  display: grid;
+  min-inline-size: 0;
+}
+
+.agent-assistant-attachment__file-text span,
+.agent-assistant-attachment__file-text small {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.agent-assistant-attachment__file-text small {
+  color: rgba(var(--v-theme-on-surface), 0.58);
+}
+
+.markdown-body {
+  overflow-wrap: anywhere;
+  word-break: break-word;
+
+  :deep(p) {
+    margin-block-end: 0.5rem;
+  }
+
+  :deep(p:last-child) {
+    margin-block-end: 0;
+  }
+
+  :deep(a) {
+    color: rgb(var(--v-theme-primary));
+    text-decoration: underline;
+  }
+
+  :deep(pre) {
+    overflow: auto;
+    padding: 0.75rem;
+    border-radius: 10px;
+    background: rgba(var(--v-theme-on-surface), 0.08);
+    margin-block: 0.5rem;
+  }
+
+  :deep(code) {
+    border-radius: 4px;
+    background: rgba(var(--v-theme-on-surface), 0.08);
+    padding-block: 0.1rem;
+    padding-inline: 0.3rem;
+  }
+
+  :deep(pre code) {
+    padding: 0;
+    background: transparent;
+  }
+
+  :deep(ul),
+  :deep(ol) {
+    margin-block-end: 0.5rem;
+    padding-inline-start: 1.25rem;
+  }
+}
+
+@keyframes agent-typing {
+  0%,
+  80%,
+  100% {
+    opacity: 0.35;
+    transform: translateY(0);
+  }
+
+  40% {
+    opacity: 1;
+    transform: translateY(-0.18rem);
+  }
+}
+
+@media (width <= 960px) {
+  .agent-assistant-panel {
+    inline-size: 100vw !important;
+  }
+}
+
+@media (width <= 600px) {
+  .agent-assistant-fab {
+    inset-block: auto max(5rem, calc(env(safe-area-inset-bottom, 0px) + 5rem));
+    transform: translateX(1.35rem);
+  }
+
+  .agent-assistant-fab:hover {
+    transform: translateX(0);
+  }
+
+  .agent-assistant-messages {
+    padding-block: 0.85rem calc(env(safe-area-inset-bottom, 0px) + 8.2rem);
+    padding-inline: 0.85rem;
+  }
+
+  .agent-assistant-composer {
+    inset-block-end: calc(env(safe-area-inset-bottom, 0px) + 0.7rem);
+    inset-inline: 0.85rem;
+  }
+}
+</style>
diff --git a/src/components/ThemeCustomizer.vue b/src/components/ThemeCustomizer.vue
index 4c1e8d63..fff625df 100644
--- a/src/components/ThemeCustomizer.vue
+++ b/src/components/ThemeCustomizer.vue
@@ -12,20 +12,9 @@ import {
 import { usePWA } from '@/composables/usePWA'
 import { useI18n } from 'vue-i18n'
 import { useTheme } from 'vuetify'
-import { VDialog, VNavigationDrawer } from 'vuetify/components'
-import { useDisplay } from 'vuetify'
-
-const props = withDefaults(
-  defineProps<{
-    modelValue?: boolean
-  }>(),
-  {
-    modelValue: false,
-  },
-)
 
 const emit = defineEmits<{
-  'update:modelValue': [value: boolean]
+  'close': []
 }>()
 
 const customColorInput = ref<HTMLInputElement | null>(null)
@@ -45,15 +34,9 @@ const {
 const { appMode } = usePWA()
 const { t } = useI18n()
 const { global: globalTheme } = useTheme()
-const display = useDisplay()
 const defaultPrimaryColor = themeCustomizerPrimaryColors[0].value
 const customizerViewportHeight = ref('100dvh')
 
-const drawer = computed({
-  get: () => props.modelValue,
-  set: value => emit('update:modelValue', value),
-})
-
 function getVisibleViewportHeight() {
   if (typeof window === 'undefined') return '100dvh'
 
@@ -87,13 +70,14 @@ function clearThemeCustomizerOpenState() {
   syncThemeCustomizerOpenState(false)
 }
 
-watch(drawer, syncThemeCustomizerOpenState, { immediate: true })
-watch(drawer, isOpen => {
-  if (isOpen) nextTick(syncCustomizerViewportHeight)
-})
+function handleGlobalKeydown(event: KeyboardEvent) {
+  // 固定侧栏不再依赖 Vuetify overlay，手动补上常见的 Esc 关闭行为。
+  if (event.key === 'Escape') emit('close')
+}
 
 onMounted(() => {
   syncCustomizerViewportHeight()
+  window.addEventListener('keydown', handleGlobalKeydown)
   window.addEventListener('resize', syncCustomizerViewportHeight)
   window.addEventListener('orientationchange', syncCustomizerViewportHeight)
   window.visualViewport?.addEventListener('resize', syncCustomizerViewportHeight)
@@ -104,41 +88,16 @@ onScopeDispose(clearThemeCustomizerOpenState)
 onScopeDispose(() => {
   if (typeof window === 'undefined') return
 
+  window.removeEventListener('keydown', handleGlobalKeydown)
   window.removeEventListener('resize', syncCustomizerViewportHeight)
   window.removeEventListener('orientationchange', syncCustomizerViewportHeight)
   window.visualViewport?.removeEventListener('resize', syncCustomizerViewportHeight)
   window.visualViewport?.removeEventListener('scroll', syncCustomizerViewportHeight)
 })
 
-const customizerContainer = computed(() => (appMode.value ? VDialog : VNavigationDrawer))
-
-const customizerContainerStyle = computed<CSSProperties>(() => {
-  if (!appMode.value) return {}
-
-  return {
-    '--theme-customizer-viewport-height': customizerViewportHeight.value,
-  }
-})
-
-const customizerContainerProps = computed(() => {
-  if (appMode.value && display.mdAndDown.value) {
-    return {
-      class: 'theme-customizer-dialog-overlay',
-      scrim: true,
-      fullscreen: !display.mdAndUp.value,
-      scrollable: true,
-    }
-  }
-
-  return {
-    class: 'theme-customizer-drawer',
-    location: 'right' as const,
-    scrim: false,
-    temporary: true,
-    width: 420,
-    persistent: false,
-  }
-})
+const customizerContainerStyle = computed<CSSProperties>(() => ({
+  '--theme-customizer-viewport-height': customizerViewportHeight.value,
+}))
 
 const themeOptions = computed<Array<{ icon: string; title: string; value: ThemeCustomizerTheme }>>(() => [
   { title: t('theme.light'), value: 'light', icon: 'mdi-white-balance-sunny' },
@@ -273,255 +232,224 @@ async function handleResetSettings() {
 </script>
 
 <template>
-  <Teleport to="body">
-    <Transition name="theme-customizer-glass">
-      <div
-        v-if="drawer"
-        class="theme-customizer-glass-backdrop"
-        :class="{ 'theme-customizer-glass-backdrop--dialog': appMode }"
-      />
-    </Transition>
-
-    <component
-      :is="customizerContainer"
-      v-model="drawer"
-      v-bind="customizerContainerProps"
-      :style="customizerContainerStyle"
-    >
-      <div
-        class="theme-customizer-panel"
-        :class="{ 'theme-customizer-panel--dialog': appMode, 'app-surface': appMode }"
-      >
-        <div class="theme-customizer-header py-5 px-4">
-          <div>
-            <h2 class="theme-customizer-title">{{ t('theme.customizer.title') }}</h2>
-          </div>
-          <div class="theme-customizer-header-actions">
-            <VBadge color="error" dot :model-value="showResetBadge" location="top end" offset-x="2" offset-y="2">
-              <IconBtn :aria-label="t('theme.customizer.reset')" @click="handleResetSettings">
-                <VIcon class="text-high-emphasis" icon="mdi-refresh" />
-              </IconBtn>
-            </VBadge>
-            <IconBtn :aria-label="t('common.close')" @click="drawer = false">
-              <VIcon class="text-high-emphasis" icon="mdi-close" />
-            </IconBtn>
-          </div>
+  <aside
+    class="theme-customizer-panel-host"
+    :style="customizerContainerStyle"
+    role="dialog"
+    :aria-label="t('theme.customizer.title')"
+  >
+    <div class="theme-customizer-panel" :class="{ 'theme-customizer-panel--dialog': appMode, 'app-surface': appMode }">
+      <div class="theme-customizer-header py-5 px-4">
+        <div>
+          <h2 class="theme-customizer-title">{{ t('theme.customizer.title') }}</h2>
         </div>
+        <div class="theme-customizer-header-actions">
+          <VBadge color="error" dot :model-value="showResetBadge" location="top end" offset-x="2" offset-y="2">
+            <IconBtn :aria-label="t('theme.customizer.reset')" @click="handleResetSettings">
+              <VIcon class="text-high-emphasis" icon="mdi-refresh" />
+            </IconBtn>
+          </VBadge>
+          <IconBtn :aria-label="t('common.close')" @click="emit('close')">
+            <VIcon class="text-high-emphasis" icon="mdi-close" />
+          </IconBtn>
+        </div>
+      </div>
 
-        <VDivider />
+      <VDivider />
 
-        <PerfectScrollbar class="theme-customizer-body" :options="{ wheelPropagation: false }">
-          <section class="theme-customizer-section">
-            <h3 class="theme-customizer-section-title">{{ t('theme.customizer.primaryColor') }}</h3>
-            <div class="theme-customizer-color-grid">
-              <div
-                v-for="color in themeCustomizerPrimaryColors"
-                :key="color.value"
-                class="theme-customizer-color-option"
-                :class="{ 'is-active': settings.primaryColor === color.value }"
-                :aria-label="t('theme.customizer.usePrimaryColor', { color: color.name })"
-                @click="setPrimaryColor(color.value)"
-              >
-                <span class="theme-customizer-color-swatch" :style="{ backgroundColor: color.value }" />
-              </div>
-
-              <div
-                v-if="!appMode"
-                class="theme-customizer-color-option theme-customizer-color-option--picker"
-                :class="{
-                  'is-active': !themeCustomizerPrimaryColors.some(color => color.value === settings.primaryColor),
-                }"
-                :aria-label="t('theme.customizer.chooseCustomColor')"
-                @click="openColorPicker"
-              >
-                <VIcon class="theme-customizer-native-icon" icon="mdi-palette-outline" size="30" />
-                <input
-                  ref="customColorInput"
-                  class="theme-customizer-native-color"
-                  type="color"
-                  :value="settings.primaryColor"
-                  @input="handleCustomColorInput"
-                />
-              </div>
+      <PerfectScrollbar class="theme-customizer-body" :options="{ wheelPropagation: false }">
+        <section class="theme-customizer-section">
+          <h3 class="theme-customizer-section-title">{{ t('theme.customizer.primaryColor') }}</h3>
+          <div class="theme-customizer-color-grid">
+            <div
+              v-for="color in themeCustomizerPrimaryColors"
+              :key="color.value"
+              class="theme-customizer-color-option"
+              :class="{ 'is-active': settings.primaryColor === color.value }"
+              :aria-label="t('theme.customizer.usePrimaryColor', { color: color.name })"
+              @click="setPrimaryColor(color.value)"
+            >
+              <span class="theme-customizer-color-swatch" :style="{ backgroundColor: color.value }" />
             </div>
 
-            <h3 class="theme-customizer-section-title">{{ t('common.theme') }}</h3>
-            <div class="theme-customizer-option-grid theme-customizer-option-grid--theme">
-              <div
-                v-for="theme in themeOptions"
-                :key="theme.value"
-                class="theme-customizer-card-option"
-                :class="{ 'is-active': settings.theme === theme.value }"
-                @click="setTheme(theme.value)"
-              >
-                <VIcon class="theme-customizer-theme-icon" :icon="theme.icon" size="36" />
-                <span>{{ theme.title }}</span>
-              </div>
-            </div>
-
-            <VDivider class="mt-7" />
-
-            <h3 class="theme-customizer-section-title">{{ t('theme.customizer.skins') }}</h3>
-            <div class="theme-customizer-preview-grid theme-customizer-preview-grid--skins">
-              <div
-                v-for="skin in skinOptions"
-                :key="skin.value"
-                class="theme-customizer-preview-option"
-                :class="{ 'is-active': settings.skin === skin.value }"
-                @click="setSkin(skin.value)"
-              >
-                <span class="theme-customizer-mini-layout" :class="`theme-customizer-mini-layout--${skin.value}`">
-                  <span class="mini-sidebar">
-                    <i />
-                    <i />
-                    <i />
-                    <i />
-                  </span>
-                  <span class="mini-content">
-                    <i />
-                    <i />
-                    <i />
-                  </span>
-                </span>
-                <span>{{ skin.title }}</span>
-              </div>
-            </div>
-
-            <VDivider class="mt-7" />
-
-            <h3 class="theme-customizer-section-title">{{ t('theme.customizer.radius') }}</h3>
-            <div class="theme-customizer-preview-grid theme-customizer-preview-grid--radius">
-              <div
-                v-for="radius in radiusOptions"
-                :key="radius.value"
-                class="theme-customizer-preview-option"
-                :class="{ 'is-active': settings.radius === radius.value }"
-                @click="setRadius(radius.value)"
-              >
-                <span
-                  class="theme-customizer-radius-scene"
-                  :style="{ '--theme-customizer-radius-preview': radius.previewRadius }"
-                >
-                  <span class="theme-customizer-radius-scene__card">
-                    <span class="theme-customizer-radius-scene__badge" />
-                    <span class="theme-customizer-radius-scene__line" />
-                    <span class="theme-customizer-radius-scene__line theme-customizer-radius-scene__line--short" />
-                  </span>
-                </span>
-                <span>{{ radius.title }}</span>
-              </div>
-            </div>
-
-            <VDivider class="mt-7" />
-
-            <h3 class="theme-customizer-section-title">{{ t('theme.customizer.shadow') }}</h3>
-            <div class="theme-customizer-preview-grid theme-customizer-preview-grid--shadow">
-              <div
-                v-for="shadow in shadowOptions"
-                :key="shadow.value"
-                class="theme-customizer-preview-option"
-                :class="{ 'is-active': settings.shadow === shadow.value }"
-                @click="setShadow(shadow.value)"
-              >
-                <span class="theme-customizer-shadow-scene" :class="`theme-customizer-shadow-scene--${shadow.value}`">
-                  <span class="theme-customizer-shadow-scene__panel">
-                    <span class="theme-customizer-shadow-scene__panel-line" />
-                    <span
-                      class="theme-customizer-shadow-scene__panel-line theme-customizer-shadow-scene__panel-line--short"
-                    />
-                  </span>
-
-                  <span class="theme-customizer-shadow-scene__card">
-                    <span class="theme-customizer-shadow-scene__badge" />
-                    <span class="theme-customizer-shadow-scene__line theme-customizer-shadow-scene__line--short" />
-                    <span class="theme-customizer-shadow-scene__line" />
-                  </span>
-                </span>
-                <span>{{ shadow.title }}</span>
-              </div>
-            </div>
-
-            <div v-if="showSemiDarkMenuOption" class="theme-customizer-semi-dark">
-              <span>{{ t('theme.customizer.semiDarkMenu') }}</span>
-              <VSwitch
-                :model-value="settings.semiDarkMenu"
-                color="primary"
-                inset
-                hide-details
-                @update:model-value="setSemiDarkMenu(Boolean($event))"
+            <div
+              v-if="!appMode"
+              class="theme-customizer-color-option theme-customizer-color-option--picker"
+              :class="{
+                'is-active': !themeCustomizerPrimaryColors.some(color => color.value === settings.primaryColor),
+              }"
+              :aria-label="t('theme.customizer.chooseCustomColor')"
+              @click="openColorPicker"
+            >
+              <VIcon class="theme-customizer-native-icon" icon="mdi-palette-outline" size="30" />
+              <input
+                ref="customColorInput"
+                class="theme-customizer-native-color"
+                type="color"
+                :value="settings.primaryColor"
+                @input="handleCustomColorInput"
               />
             </div>
-          </section>
+          </div>
 
-          <VDivider v-if="showLayoutSection" />
-
-          <section v-if="showLayoutSection" class="theme-customizer-section">
-            <h3 class="theme-customizer-section-title">{{ t('theme.customizer.layout') }}</h3>
-            <div class="theme-customizer-preview-grid">
-              <div
-                v-for="layout in layoutOptions"
-                :key="layout.value"
-                class="theme-customizer-preview-option"
-                :class="{ 'is-active': settings.layout === layout.value, 'is-disabled': appMode }"
-                @click="handleLayoutChange(layout.value)"
-              >
-                <span class="theme-customizer-mini-layout" :class="`theme-customizer-mini-layout--${layout.value}`">
-                  <span class="mini-sidebar">
-                    <i />
-                    <i />
-                    <i />
-                  </span>
-                  <span class="mini-content">
-                    <i />
-                    <i />
-                    <i />
-                  </span>
-                </span>
-                <span>{{ layout.title }}</span>
-              </div>
+          <h3 class="theme-customizer-section-title">{{ t('common.theme') }}</h3>
+          <div class="theme-customizer-option-grid theme-customizer-option-grid--theme">
+            <div
+              v-for="theme in themeOptions"
+              :key="theme.value"
+              class="theme-customizer-card-option"
+              :class="{ 'is-active': settings.theme === theme.value }"
+              @click="setTheme(theme.value)"
+            >
+              <VIcon class="theme-customizer-theme-icon" :icon="theme.icon" size="36" />
+              <span>{{ theme.title }}</span>
             </div>
-          </section>
-        </PerfectScrollbar>
-      </div>
-    </component>
-  </Teleport>
+          </div>
+
+          <VDivider class="mt-7" />
+
+          <h3 class="theme-customizer-section-title">{{ t('theme.customizer.skins') }}</h3>
+          <div class="theme-customizer-preview-grid theme-customizer-preview-grid--skins">
+            <div
+              v-for="skin in skinOptions"
+              :key="skin.value"
+              class="theme-customizer-preview-option"
+              :class="{ 'is-active': settings.skin === skin.value }"
+              @click="setSkin(skin.value)"
+            >
+              <span class="theme-customizer-mini-layout" :class="`theme-customizer-mini-layout--${skin.value}`">
+                <span class="mini-sidebar">
+                  <i />
+                  <i />
+                  <i />
+                  <i />
+                </span>
+                <span class="mini-content">
+                  <i />
+                  <i />
+                  <i />
+                </span>
+              </span>
+              <span>{{ skin.title }}</span>
+            </div>
+          </div>
+
+          <VDivider class="mt-7" />
+
+          <h3 class="theme-customizer-section-title">{{ t('theme.customizer.radius') }}</h3>
+          <div class="theme-customizer-preview-grid theme-customizer-preview-grid--radius">
+            <div
+              v-for="radius in radiusOptions"
+              :key="radius.value"
+              class="theme-customizer-preview-option"
+              :class="{ 'is-active': settings.radius === radius.value }"
+              @click="setRadius(radius.value)"
+            >
+              <span
+                class="theme-customizer-radius-scene"
+                :style="{ '--theme-customizer-radius-preview': radius.previewRadius }"
+              >
+                <span class="theme-customizer-radius-scene__card">
+                  <span class="theme-customizer-radius-scene__badge" />
+                  <span class="theme-customizer-radius-scene__line" />
+                  <span class="theme-customizer-radius-scene__line theme-customizer-radius-scene__line--short" />
+                </span>
+              </span>
+              <span>{{ radius.title }}</span>
+            </div>
+          </div>
+
+          <VDivider class="mt-7" />
+
+          <h3 class="theme-customizer-section-title">{{ t('theme.customizer.shadow') }}</h3>
+          <div class="theme-customizer-preview-grid theme-customizer-preview-grid--shadow">
+            <div
+              v-for="shadow in shadowOptions"
+              :key="shadow.value"
+              class="theme-customizer-preview-option"
+              :class="{ 'is-active': settings.shadow === shadow.value }"
+              @click="setShadow(shadow.value)"
+            >
+              <span class="theme-customizer-shadow-scene" :class="`theme-customizer-shadow-scene--${shadow.value}`">
+                <span class="theme-customizer-shadow-scene__panel">
+                  <span class="theme-customizer-shadow-scene__panel-line" />
+                  <span
+                    class="theme-customizer-shadow-scene__panel-line theme-customizer-shadow-scene__panel-line--short"
+                  />
+                </span>
+
+                <span class="theme-customizer-shadow-scene__card">
+                  <span class="theme-customizer-shadow-scene__badge" />
+                  <span class="theme-customizer-shadow-scene__line theme-customizer-shadow-scene__line--short" />
+                  <span class="theme-customizer-shadow-scene__line" />
+                </span>
+              </span>
+              <span>{{ shadow.title }}</span>
+            </div>
+          </div>
+
+          <div v-if="showSemiDarkMenuOption" class="theme-customizer-semi-dark">
+            <span>{{ t('theme.customizer.semiDarkMenu') }}</span>
+            <VSwitch
+              :model-value="settings.semiDarkMenu"
+              color="primary"
+              inset
+              hide-details
+              @update:model-value="setSemiDarkMenu(Boolean($event))"
+            />
+          </div>
+        </section>
+
+        <VDivider v-if="showLayoutSection" />
+
+        <section v-if="showLayoutSection" class="theme-customizer-section">
+          <h3 class="theme-customizer-section-title">{{ t('theme.customizer.layout') }}</h3>
+          <div class="theme-customizer-preview-grid">
+            <div
+              v-for="layout in layoutOptions"
+              :key="layout.value"
+              class="theme-customizer-preview-option"
+              :class="{ 'is-active': settings.layout === layout.value, 'is-disabled': appMode }"
+              @click="handleLayoutChange(layout.value)"
+            >
+              <span class="theme-customizer-mini-layout" :class="`theme-customizer-mini-layout--${layout.value}`">
+                <span class="mini-sidebar">
+                  <i />
+                  <i />
+                  <i />
+                </span>
+                <span class="mini-content">
+                  <i />
+                  <i />
+                  <i />
+                </span>
+              </span>
+              <span>{{ layout.title }}</span>
+            </div>
+          </div>
+        </section>
+      </PerfectScrollbar>
+    </div>
+  </aside>
 </template>
 
-<style lang="scss">
+<style lang="scss" scoped>
 /* stylelint-disable no-descending-specificity */
 
-.theme-customizer-drawer {
+.theme-customizer-panel-host {
   position: fixed !important;
-  z-index: 12000 !important;
+  z-index: 2102 !important;
+  display: flex;
   overflow: hidden;
-  block-size: 100dvh !important;
+  border-radius: 0;
+  background: rgb(var(--v-theme-surface));
+  block-size: var(--theme-customizer-viewport-height, 100dvh) !important;
   border-inline-start: 1px solid rgba(var(--v-theme-on-surface), 0.08) !important;
   box-shadow: var(--app-surface-shadow) !important;
-  inset-block: 0 !important;
+  inline-size: 420px !important;
+  inset-block-start: 0 !important;
   inset-inline-end: 0 !important;
-  max-block-size: 100dvh !important;
-
-  .v-navigation-drawer__content {
-    position: relative;
-    z-index: 1;
-    display: flex;
-    overflow: hidden;
-    flex-direction: column;
-    block-size: 100%;
-  }
-}
-
-.theme-customizer-dialog-overlay {
-  --theme-customizer-viewport-height: 100dvh;
-
-  z-index: 12000 !important;
-}
-
-.theme-customizer-dialog-overlay > .v-overlay__content {
-  overflow: hidden;
-  block-size: var(--theme-customizer-viewport-height);
-  margin-block: 0 !important;
-  max-block-size: var(--theme-customizer-viewport-height);
+  max-block-size: var(--theme-customizer-viewport-height, 100dvh) !important;
 }
 
 .theme-customizer-panel {
@@ -529,16 +457,16 @@ async function handleResetSettings() {
   display: flex;
   flex-direction: column;
   block-size: 100%;
+  inline-size: 100%;
   min-block-size: 0;
 }
 
 .theme-customizer-panel--dialog {
   overflow: hidden;
-  background: rgb(var(--v-theme-surface));
-  block-size: var(--theme-customizer-viewport-height, 100dvh);
-  max-block-size: var(--theme-customizer-viewport-height, 100dvh);
+  block-size: 100%;
+  max-block-size: 100%;
 
-  /* fullscreen dialog 会贴到 viewport-fit=cover 顶部，iOS 需要在面板内部避开系统状态栏。 */
+  /* 独立 App 模式会贴近 viewport-fit=cover 顶部，面板内部需要避开 iOS 状态栏。 */
   padding-block-start: env(safe-area-inset-top);
 }
 
@@ -547,73 +475,12 @@ async function handleResetSettings() {
   padding-block-end: env(safe-area-inset-bottom);
 }
 
-.theme-customizer-drawer.v-theme--transparent,
-.v-theme--transparent .theme-customizer-drawer,
-html[data-theme='transparent'] .theme-customizer-drawer,
-.v-theme--transparent .theme-customizer-panel--dialog,
-html[data-theme='transparent'] .theme-customizer-panel--dialog {
-  background: transparent !important;
-}
-
-.theme-customizer-glass-backdrop {
-  position: fixed;
-  z-index: 11999;
-  block-size: 100dvh;
-  inline-size: 420px;
-  inset-block: 0;
-  inset-inline-end: 0;
-  opacity: 0;
-  pointer-events: none;
-  transform: translateX(0);
-}
-
-:is(html[data-theme='transparent'], .v-theme--transparent) .theme-customizer-glass-backdrop {
-  backdrop-filter: blur(var(--transparent-blur-heavy, 16px));
-  background-color: rgba(var(--v-theme-surface), var(--transparent-opacity-heavy, 0.5));
-  opacity: 1;
-}
-
-.theme-customizer-glass-enter-active,
-.theme-customizer-glass-leave-active {
-  transition:
-    opacity 0.2s cubic-bezier(0.4, 0, 0.2, 1),
-    transform 0.2s cubic-bezier(0.4, 0, 0.2, 1);
-}
-
-.theme-customizer-glass-enter-from,
-.theme-customizer-glass-leave-to {
-  opacity: 0 !important;
-  transform: translateX(100%);
-}
-
-:is(html[data-theme='transparent'], .v-theme--transparent) .theme-customizer-drawer .v-navigation-drawer__content {
-  background: transparent !important;
-}
-
 @media (width <= 600px) {
-  .theme-customizer-glass-backdrop {
-    inline-size: 100vw;
+  .theme-customizer-panel-host {
+    inline-size: 100vw !important;
   }
 }
 
-// 透明主题的全局 overlay 毛玻璃会影响临时抽屉绘制，主题定制器改由 drawer 自身承担背景。
-html[data-theme='transparent'] .v-overlay__content:has(.theme-customizer-drawer),
-.v-theme--transparent .v-overlay__content:has(.theme-customizer-drawer) {
-  border-radius: 0 !important;
-  backdrop-filter: none !important;
-  background: transparent !important;
-  box-shadow: none !important;
-}
-
-:is(html[data-theme='transparent'], .v-theme--transparent) .theme-customizer-card-option .theme-customizer-theme-icon,
-:is(html[data-theme='transparent'], .v-theme--transparent)
-  .theme-customizer-color-option
-  .theme-customizer-native-icon {
-  backdrop-filter: none !important;
-  background: transparent !important;
-  box-shadow: none !important;
-}
-
 .theme-customizer-header {
   display: flex;
   align-items: center;
@@ -1030,10 +897,6 @@ html[data-theme='transparent'] .v-overlay__content:has(.theme-customizer-drawer)
 }
 
 @media (width <= 600px) {
-  .theme-customizer-drawer {
-    inline-size: min(100vw, 420px) !important;
-  }
-
   .theme-customizer-header,
   .theme-customizer-section {
     padding-inline: 22px;
diff --git a/src/components/dialog/CustomCssDialog.vue b/src/components/dialog/CustomCssDialog.vue
index d81e08e5..efb03adf 100644
--- a/src/components/dialog/CustomCssDialog.vue
+++ b/src/components/dialog/CustomCssDialog.vue
@@ -99,9 +99,9 @@ function submitCustomCSS() {
 <style scoped>
 .custom-css-dialog {
   display: flex;
+  overflow: hidden;
   flex-direction: column;
   max-block-size: calc(100dvh - 2rem);
-  overflow: hidden;
 }
 
 .custom-css-header {
@@ -111,7 +111,7 @@ function submitCustomCSS() {
 
 .custom-css-editor-body {
   flex: 1 1 auto;
-  min-block-size: 0;
+  min-block-size: 240px;
 }
 
 .custom-css-editor {
@@ -141,8 +141,8 @@ function submitCustomCSS() {
 
   .custom-css-editor {
     flex: 1 1 auto;
-    min-block-size: 0;
     block-size: auto;
+    min-block-size: 0;
   }
 
   .custom-css-actions {
diff --git a/src/composables/useThemeCustomizer.ts b/src/composables/useThemeCustomizer.ts
index 8eac94dd..44d6d6bc 100644
--- a/src/composables/useThemeCustomizer.ts
+++ b/src/composables/useThemeCustomizer.ts
@@ -7,6 +7,7 @@ import { themeManager } from '@/utils/themeManager'
 
 export const THEME_CUSTOMIZER_STORAGE_KEY = 'moviepilot-theme-customizer'
 export const THEME_CUSTOMIZER_CHANGE_EVENT = 'moviepilot-theme-customizer-change'
+export const THEME_CUSTOMIZER_OPEN_EVENT = 'moviepilot-theme-customizer-open'
 
 export const themeCustomizerPrimaryColors = [
   { name: 'Purple', value: '#9155FD' },
diff --git a/src/layouts/components/DefaultLayout.vue b/src/layouts/components/DefaultLayout.vue
index 77896f45..3be84395 100644
--- a/src/layouts/components/DefaultLayout.vue
+++ b/src/layouts/components/DefaultLayout.vue
@@ -9,7 +9,9 @@ import ShortcutBar from '@/layouts/components/ShortcutBar.vue'
 import UserProfile from '@/layouts/components/UserProfile.vue'
 import QuickAccess from '@/layouts/components/QuickAccess.vue'
 import HeaderTab from '@/layouts/components/HeaderTab.vue'
-import { usePluginSidebarNavStore, useUserStore } from '@/stores'
+import AgentAssistantWidget from '@/components/AgentAssistantWidget.vue'
+import ThemeCustomizer from '@/components/ThemeCustomizer.vue'
+import { useGlobalSettingsStore, usePluginSidebarNavStore, useUserStore } from '@/stores'
 import { getNavMenus } from '@/router/i18n-menu'
 import { filterPluginSidebarNavEntries } from '@/utils/pluginSidebarNav'
 import { NavMenu } from '@/@layouts/types'
@@ -31,6 +33,7 @@ import { useGlobalOfflineStatus } from '@/composables/useOfflineStatus'
 import {
   readThemeCustomizerSettings,
   THEME_CUSTOMIZER_CHANGE_EVENT,
+  THEME_CUSTOMIZER_OPEN_EVENT,
   type ThemeCustomizerSettings,
 } from '@/composables/useThemeCustomizer'
 import logo from '@images/logo.svg?raw'
@@ -42,14 +45,17 @@ const { t } = useI18n()
 const route = useRoute()
 const router = useRouter()
 const themeLayout = ref(readThemeCustomizerSettings().layout)
+const showThemeCustomizer = ref(false)
 
 // 用户 Store
 const userStore = useUserStore()
 const pluginSidebarNavStore = usePluginSidebarNavStore()
+const globalSettingsStore = useGlobalSettingsStore()
 
 // 获取用户权限信息
 const userPermissions = computed(() => buildUserPermissionContext(userStore.superUser, userStore.permissions))
 const canAdmin = computed(() => hasPermission(userPermissions.value, 'admin'))
+const showAgentAssistant = computed(() => canAdmin.value && globalSettingsStore.get('AI_AGENT_ENABLE') === true)
 
 // 开始菜单项
 const startMenus = ref<NavMenu[]>([])
@@ -279,6 +285,10 @@ function handleThemeCustomizerChange(event: Event) {
   themeLayout.value = (event as CustomEvent<ThemeCustomizerSettings>).detail.layout
 }
 
+function handleThemeCustomizerOpen() {
+  showThemeCustomizer.value = true
+}
+
 function isHorizontalNavActive(item: NavMenu) {
   const targetPath = normalizeMenuPath(item.to)
   if (!targetPath) return false
@@ -416,6 +426,10 @@ function appendPluginSidebarMenus() {
 }
 
 onMounted(async () => {
+  // 主题定制器由布局统一承载，监听需要尽早注册，避免异步加载菜单期间丢失打开事件。
+  window.addEventListener(THEME_CUSTOMIZER_CHANGE_EVENT, handleThemeCustomizerChange)
+  window.addEventListener(THEME_CUSTOMIZER_OPEN_EVENT, handleThemeCustomizerOpen)
+
   // 获取菜单列表
   startMenus.value = getMenuList(t('menu.start'))
   discoveryMenus.value = getMenuList(t('menu.discovery'))
@@ -431,11 +445,10 @@ onMounted(async () => {
     navigator.serviceWorker.addEventListener('message', handleServiceWorkerMessage)
   }
 
-  window.addEventListener(THEME_CUSTOMIZER_CHANGE_EVENT, handleThemeCustomizerChange)
-
   // 组件卸载时清理监听
   onBeforeUnmount(() => {
     window.removeEventListener(THEME_CUSTOMIZER_CHANGE_EVENT, handleThemeCustomizerChange)
+    window.removeEventListener(THEME_CUSTOMIZER_OPEN_EVENT, handleThemeCustomizerOpen)
     if ('serviceWorker' in navigator) {
       navigator.serviceWorker.removeEventListener('message', handleServiceWorkerMessage)
     }
@@ -692,6 +705,12 @@ onMounted(async () => {
     @close="handleClosePluginQuickAccess"
     @plugin-click="handlePluginClick"
   />
+
+  <!-- 👉 Theme Customizer -->
+  <ThemeCustomizer v-if="showThemeCustomizer" @close="showThemeCustomizer = false" />
+
+  <!-- 👉 Agent Assistant -->
+  <AgentAssistantWidget v-if="showAgentAssistant" />
 </template>
 
 <style lang="scss" scoped>
diff --git a/src/layouts/components/UserProfile.vue b/src/layouts/components/UserProfile.vue
index be69198e..be5a02fb 100644
--- a/src/layouts/components/UserProfile.vue
+++ b/src/layouts/components/UserProfile.vue
@@ -20,6 +20,7 @@ import {
   persistPartialThemeCustomizerSettings,
   readThemeCustomizerSettings,
   THEME_CUSTOMIZER_CHANGE_EVENT,
+  THEME_CUSTOMIZER_OPEN_EVENT,
   type ThemeCustomizerSettings,
 } from '@/composables/useThemeCustomizer'
 import { buildUserPermissionContext, hasPermission } from '@/utils/permission'
@@ -30,7 +31,6 @@ const ProgressDialog = defineAsyncComponent(() => import('@/components/dialog/Pr
 const TransparencySettingsDialog = defineAsyncComponent(
   () => import('@/components/dialog/TransparencySettingsDialog.vue'),
 )
-const ThemeCustomizer = defineAsyncComponent(() => import('@/components/ThemeCustomizer.vue'))
 const UserAuthDialog = defineAsyncComponent(() => import('@/components/dialog/UserAuthDialog.vue'))
 
 // 认证 Store
@@ -50,12 +50,12 @@ const $toast = useToast()
 // UI模式菜单是否显示
 const showUIModeMenu = ref(false)
 
+// 用户头像主菜单是否显示；打开布局级面板前需要主动关闭，避免菜单 overlay 残留。
+const showUserMenu = ref(false)
+
 // 主题菜单是否显示
 const showThemeMenu = ref(false)
 
-// 主题定制器面板是否显示
-const showThemeCustomizer = ref(false)
-
 // 语言菜单是否显示
 const showLanguageMenu = ref(false)
 
@@ -442,8 +442,11 @@ function showTransparencySettingsDialog() {
 
 /** 从用户菜单打开主题定制器，App 模式会在面板内部隐藏布局设置。 */
 function showThemeCustomizerDrawer() {
+  showUserMenu.value = false
   showThemeMenu.value = false
-  showThemeCustomizer.value = true
+
+  // 主题定制器由 DefaultLayout 统一挂载
+  window.dispatchEvent(new CustomEvent(THEME_CUSTOMIZER_OPEN_EVENT))
 }
 
 /** 保存自定义 CSS。 */
@@ -558,6 +561,7 @@ onUnmounted(() => {
     <VImg :src="avatar" />
 
     <VMenu
+      v-model="showUserMenu"
       activator="parent"
       width="15rem"
       location="bottom end"
@@ -777,7 +781,6 @@ onUnmounted(() => {
     </VMenu>
     <!-- !SECTION -->
   </VAvatar>
-  <ThemeCustomizer v-model="showThemeCustomizer" />
 </template>
 
 <style lang="scss" scoped>
diff --git a/src/locales/en-US.ts b/src/locales/en-US.ts
index e7b5db0d..e3f085d9 100644
--- a/src/locales/en-US.ts
+++ b/src/locales/en-US.ts
@@ -697,6 +697,19 @@ export default {
       subtitle: 'Scheduled Services',
     },
   },
+  agentAssistant: {
+    title: 'AI Assistant',
+    assistant: 'Assistant',
+    ready: 'Ready',
+    thinking: 'Thinking',
+    newChat: 'New Chat',
+    emptyTitle: 'Ask about sites, subscriptions, downloads, or organization tasks',
+    placeholder: 'Ask MoviePilot...',
+    stop: 'Stop generating',
+    download: 'Download',
+    error: 'Assistant response failed',
+    noStream: 'This browser cannot read streaming responses',
+  },
   workflow: {
     components: 'Action Components',
     clickToAdd: 'Click to Add',
diff --git a/src/locales/zh-CN.ts b/src/locales/zh-CN.ts
index 2aaa670f..0a442c7b 100644
--- a/src/locales/zh-CN.ts
+++ b/src/locales/zh-CN.ts
@@ -693,6 +693,19 @@ export default {
       subtitle: '定时服务',
     },
   },
+  agentAssistant: {
+    title: '智能助手',
+    assistant: '助手',
+    ready: '随时待命',
+    thinking: '思考中',
+    newChat: '新会话',
+    emptyTitle: '可以直接询问站点、订阅、下载和整理任务',
+    placeholder: '询问 MoviePilot...',
+    stop: '停止生成',
+    download: '下载',
+    error: '智能助手响应失败',
+    noStream: '当前浏览器无法读取流式响应',
+  },
   workflow: {
     components: '动作组件',
     clickToAdd: '点击添加',
diff --git a/src/locales/zh-TW.ts b/src/locales/zh-TW.ts
index 1839f831..78870417 100644
--- a/src/locales/zh-TW.ts
+++ b/src/locales/zh-TW.ts
@@ -693,6 +693,19 @@ export default {
       subtitle: '定時服務',
     },
   },
+  agentAssistant: {
+    title: '智能助手',
+    assistant: '助手',
+    ready: '隨時待命',
+    thinking: '思考中',
+    newChat: '新會話',
+    emptyTitle: '可以直接詢問站點、訂閱、下載和整理任務',
+    placeholder: '詢問 MoviePilot...',
+    stop: '停止生成',
+    download: '下載',
+    error: '智能助手響應失敗',
+    noStream: '目前瀏覽器無法讀取串流響應',
+  },
   workflow: {
     components: '動作組件',
     clickToAdd: '點擊添加',
diff --git a/src/styles/common.scss b/src/styles/common.scss
index 540be09b..bcbed6fc 100644
--- a/src/styles/common.scss
+++ b/src/styles/common.scss
@@ -922,6 +922,7 @@ html[data-theme="transparent"] .app-card-colorful,
 }
 
 :root {
+  --agent-assistant-fab-offset: 30rem;
   --theme-customizer-fab-offset: 420px;
 }
 
@@ -1040,6 +1041,14 @@ html[data-theme="transparent"] .app-card-colorful,
   html[data-theme-customizer-open='true'] .global-action-buttons {
     inset-inline-end: calc(var(--theme-customizer-fab-offset) + 2rem);
   }
+
+  html[data-agent-assistant-open='true'] .compact-fab-stack {
+    inset-inline-end: calc(var(--agent-assistant-fab-offset) + max(1rem, calc(env(safe-area-inset-right) + 1rem)));
+  }
+
+  html[data-agent-assistant-open='true'] .global-action-buttons {
+    inset-inline-end: calc(var(--agent-assistant-fab-offset) + 2rem);
+  }
 }
 
 @media (width >= 601px) and (width <= 768px) {
@@ -1048,6 +1057,12 @@ html[data-theme="transparent"] .app-card-colorful,
       var(--theme-customizer-fab-offset) + max(0.875rem, calc(env(safe-area-inset-right) + 0.875rem))
     );
   }
+
+  html[data-agent-assistant-open='true'] .compact-fab-stack {
+    inset-inline-end: calc(
+      var(--agent-assistant-fab-offset) + max(0.875rem, calc(env(safe-area-inset-right) + 0.875rem))
+    );
+  }
 }
 
 .apexcharts-title-text {