@movk/nuxt-docs 1.6.2 → 1.7.0

package/modules/ai-chat/index.ts

@@ -1,13 +1,16 @@
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
-import { addComponentsDir, addImportsDir, addServerHandler, createResolver, defineNuxtModule } from '@nuxt/kit'
+import {
+  addComponent,
+  addComponentsDir,
+  addImports,
+  addServerHandler,
+  createResolver,
+  defineNuxtModule,
+  logger
+} from '@nuxt/kit'
 
 export interface AiChatModuleOptions {
-  /**
-   * 是否启用 AI 聊天功能
-   * @default import.meta.env.AI_GATEWAY_API_KEY || import.meta.env.OPENROUTER_API_KEY
-   */
-  enable?: boolean
   /**
    * 聊天 API 端点路径
    * @default '/api/ai-chat'
@@ -29,43 +32,72 @@ export interface AiChatModuleOptions {
   models?: string[]
 }
 
+const log = logger.withTag('docus:ai-assistant')
+
 export default defineNuxtModule<AiChatModuleOptions>({
   meta: {
     name: 'ai-chat',
     configKey: 'aiChat'
   },
   defaults: {
-    enable: !!(
-      import.meta.env.AI_GATEWAY_API_KEY
-        || import.meta.env.OPENROUTER_API_KEY
-    ),
     apiPath: '/api/ai-chat',
     mcpPath: '/mcp',
     model: '',
     models: []
   },
   setup(options, nuxt) {
+    const hasApiKey = !!(process.env.AI_GATEWAY_API_KEY || process.env.OPENROUTER_API_KEY)
+
     const { resolve } = createResolver(import.meta.url)
 
     nuxt.options.runtimeConfig.public.aiChat = {
-      enable: options.enable!,
+      enabled: hasApiKey,
       apiPath: options.apiPath!,
       model: options.model!,
       models: options.models!
     }
-    nuxt.options.runtimeConfig.aiChat = {
-      mcpPath: options.mcpPath!
+
+    addImports([
+      {
+        name: 'useAIChat',
+        from: resolve('./runtime/composables/useAIChat')
+      }
+    ])
+
+    if (hasApiKey) {
+      addComponentsDir({
+        path: resolve('./runtime/components'),
+        ignore: ['AiChatDisabled']
+      })
+    } else {
+      addComponent({
+        name: 'AiChatDisabled',
+        filePath: resolve('./runtime/components/AiChatDisabled.vue')
+      })
     }
 
-    if (!options.enable) {
-      console.info('[ai-chat] Module disabled: no AI_GATEWAY_API_KEY or OPENROUTER_API_KEY found')
+    if (!hasApiKey) {
+      log.warn('[ai-chat] Module disabled: no AI_GATEWAY_API_KEY or OPENROUTER_API_KEY found')
+      return
     }
 
-    addComponentsDir({
-      path: resolve('runtime/components')
-    })
+    nuxt.options.runtimeConfig.aiChat = {
+      mcpPath: options.mcpPath!
+    }
+
+    addImports([
+      {
+        name: 'useHighlighter',
+        from: resolve('./runtime/composables/useHighlighter')
+      }
+    ])
 
-    addImportsDir(resolve('runtime/composables'))
+    addImports([
+      {
+        name: 'useModels',
+        from: resolve('./runtime/composables/useModels')
+      }
+    ])
 
     /**
      * 检查用户项目中是否存在自定义 handler
@@ -87,7 +119,7 @@ export default defineNuxtModule<AiChatModuleOptions>({
         handler: resolve('./runtime/server/api/ai-chat')
       })
     } else {
-      console.info(`[ai-chat] Using custom handler, skipping default handler registration`)
+      log.info(`[ai-chat] Using custom handler, skipping default handler registration`)
     }
   }
 })
@@ -95,7 +127,7 @@ export default defineNuxtModule<AiChatModuleOptions>({
 declare module 'nuxt/schema' {
   interface PublicRuntimeConfig {
     aiChat: {
-      enable: boolean
+      enabled: boolean
       apiPath: string
       model: string
       models: string[]

package/modules/ai-chat/runtime/components/AiChat.vue

@@ -1,21 +1,15 @@
 <script setup lang="ts">
-const { tooltipText = '向 AI 提问' } = defineProps<{
-  /**
-   * 鼠标悬停时的提示文本
-   * @defaultValue 向 AI 提问
-   */
-  tooltipText?: string
-}>()
-
+const { aiChat } = useAppConfig()
 const { toggle } = useAIChat()
 </script>
 
 <template>
-  <UTooltip :text="tooltipText">
+  <UTooltip :text="aiChat.texts.trigger">
     <UButton
-      icon="i-lucide-sparkles"
+      :icon="aiChat.icons.trigger"
       variant="ghost"
       class="rounded-full"
+      aria-label="AI Chat Trigger"
       @click="toggle"
     />
   </UTooltip>

package/modules/ai-chat/runtime/components/AiChatDisabled.vue

@@ -0,0 +1,3 @@
+<template>
+  <div />
+</template>

package/modules/ai-chat/runtime/components/AiChatFloatingInput.vue

@@ -2,11 +2,24 @@
 import { sleep } from '@movk/core'
 import { AnimatePresence, motion } from 'motion-v'
 
+const route = useRoute()
+const { aiChat } = useAppConfig()
 const { open, isOpen } = useAIChat()
+
 const input = ref('')
 const isVisible = ref(true)
 const inputRef = ref<{ inputRef: HTMLInputElement } | null>(null)
 
+const isDocsRoute = computed(() => route.meta.layout === 'docs')
+const isFloatingInputEnabled = computed(() => aiChat.floatingInput !== false)
+const focusInputShortcut = computed(() => aiChat.shortcuts.focusInput)
+
+const shortcutDisplayKeys = computed(() => {
+  const shortcut = focusInputShortcut.value
+  const parts = shortcut.split('_')
+  return parts.map(part => part === 'meta' ? 'meta' : part.toUpperCase())
+})
+
 function handleSubmit() {
   if (!input.value.trim()) return
 
@@ -20,10 +33,11 @@ function handleSubmit() {
   })
 }
 
-defineShortcuts({
-  meta_i: {
+const shortcuts = computed(() => ({
+  [focusInputShortcut.value]: {
     usingInput: true,
     handler: () => {
+      if (!isDocsRoute.value || !isFloatingInputEnabled.value) return
       inputRef.value?.inputRef?.focus()
     }
   },
@@ -33,13 +47,15 @@ defineShortcuts({
       inputRef.value?.inputRef?.blur()
     }
   }
-})
+}))
+
+defineShortcuts(shortcuts)
 </script>
 
 <template>
   <AnimatePresence>
     <motion.div
-      v-if="isVisible && !isOpen"
+      v-if="isFloatingInputEnabled && isDocsRoute && isVisible && !isOpen"
       key="floating-input"
       :initial="{ y: 20, opacity: 0 }"
       :animate="{ y: 0, opacity: 1 }"
@@ -48,11 +64,11 @@ defineShortcuts({
       class="fixed bottom-6 left-1/2 -translate-x-1/2 z-50 px-4"
       style="will-change: transform"
     >
-      <UForm @submit="handleSubmit">
+      <UForm @submit.prevent="handleSubmit">
         <UInput
           ref="inputRef"
           v-model="input"
-          placeholder="输入你的问题..."
+          :placeholder="aiChat.texts.placeholder"
           size="lg"
           :ui="{
             root: 'w-72 py-0.5 focus-within:w-96 transition-all duration-300 ease-out',
@@ -64,17 +80,16 @@ defineShortcuts({
           <template #trailing>
             <div class="flex items-center gap-2">
               <div class="hidden sm:!flex items-center gap-1">
-                <UKbd value="meta" />
-                <UKbd value="I" />
+                <UKbd v-for="key in shortcutDisplayKeys" :key="key" :value="key" />
               </div>
 
               <UButton
+                aria-label="Send Message"
                 type="submit"
                 icon="i-lucide-arrow-up"
                 color="primary"
                 size="xs"
                 :disabled="!input.trim()"
-                class="rounded-lg"
               />
             </div>
           </template>

package/modules/ai-chat/runtime/components/AiChatModelSelect.vue

@@ -1,4 +1,6 @@
 <script setup lang="ts">
+import { useModels } from '../composables/useModels'
+
 const { model, models, formatModelName, getModelIcon } = useModels()
 
 const items = computed(() => models.map(model => ({

package/modules/ai-chat/runtime/components/AiChatPanel.vue

@@ -0,0 +1,318 @@
+<script setup lang="ts">
+import type { DefineComponent } from 'vue'
+import type { UIMessage } from 'ai'
+import { Chat } from '@ai-sdk/vue'
+import { DefaultChatTransport } from 'ai'
+import { createReusableTemplate } from '@vueuse/core'
+import AiChatPreStream from './AiChatPreStream.vue'
+import { useModels } from '../composables/useModels'
+
+const components = {
+  pre: AiChatPreStream as unknown as DefineComponent
+}
+
+const [DefineChatContent, ReuseChatContent] = createReusableTemplate<{ showExpandButton?: boolean }>()
+
+const { isOpen, isExpanded, isMobile, panelWidth, toggleExpanded, messages, pendingMessage, clearPending, faqQuestions } = useAIChat()
+const config = useRuntimeConfig()
+const { aiChat } = useAppConfig()
+const toast = useToast()
+const { model } = useModels()
+
+const input = ref('')
+
+const chat = new Chat({
+  messages: messages.value,
+  transport: new DefaultChatTransport({
+    api: config.public.aiChat.apiPath,
+    body: () => ({ model: model.value })
+  }),
+  onError: (error: Error) => {
+    const message = (() => {
+      try {
+        const parsed = JSON.parse(error.message)
+        return parsed?.message || error.message
+      } catch {
+        return error.message
+      }
+    })()
+
+    toast.add({
+      description: message,
+      icon: 'i-lucide-circle-alert',
+      color: 'error',
+      duration: 0
+    })
+  },
+  onFinish: () => {
+    messages.value = chat.messages
+  }
+})
+
+watch(pendingMessage, (message: string | undefined) => {
+  if (message) {
+    if (messages.value.length === 0 && chat.messages.length > 0) {
+      chat.messages.length = 0
+    }
+    chat.sendMessage({
+      text: message
+    })
+    clearPending()
+  }
+}, { immediate: true })
+
+watch(messages, (newMessages: UIMessage[]) => {
+  if (newMessages.length === 0 && chat.messages.length > 0) {
+    chat.messages.length = 0
+  }
+}, { deep: true })
+
+const lastMessage = computed(() => chat.messages.at(-1))
+
+const { tools } = useToolCall()
+function getToolLabel(toolName: string, args?: any): string {
+  const label = tools[toolName]
+
+  if (!label) {
+    return toolName
+  }
+
+  return typeof label === 'function' ? label(args) : label
+}
+
+function handleSubmit(event?: Event) {
+  event?.preventDefault()
+
+  if (!input.value.trim()) {
+    return
+  }
+
+  chat.sendMessage({
+    text: input.value
+  })
+
+  input.value = ''
+}
+
+function askQuestion(question: string) {
+  chat.sendMessage({
+    text: question
+  })
+}
+
+function resetChat() {
+  chat.stop()
+  messages.value = []
+  chat.messages.length = 0
+}
+
+onMounted(() => {
+  if (pendingMessage.value) {
+    chat.sendMessage({
+      text: pendingMessage.value
+    })
+    clearPending()
+  } else if (chat.lastMessage?.role === 'user') {
+    chat.regenerate()
+  }
+})
+</script>
+
+<template>
+  <DefineChatContent v-slot="{ showExpandButton = true }">
+    <div class="flex h-full flex-col">
+      <div class="flex h-16 shrink-0 items-center justify-between border-b border-muted/50 px-4">
+        <span class="font-medium text-highlighted">{{ aiChat.texts.title }}</span>
+        <div class="flex items-center gap-1">
+          <UTooltip
+            v-if="showExpandButton"
+            :text="isExpanded ? aiChat.texts.collapse : aiChat.texts.expand"
+          >
+            <UButton
+              :icon="isExpanded ? 'i-lucide-minimize-2' : 'i-lucide-maximize-2'"
+              color="neutral"
+              variant="ghost"
+              size="sm"
+              class="text-muted hover:text-highlighted"
+              aria-label="Toggle Expand Chat Panel"
+              @click="toggleExpanded"
+            />
+          </UTooltip>
+          <UTooltip
+            v-if="chat.messages.length > 0"
+            :text="aiChat.texts.clearChat"
+          >
+            <UButton
+              :icon="aiChat.icons.clearChat"
+              color="neutral"
+              variant="ghost"
+              size="sm"
+              class="text-muted hover:text-highlighted"
+              aria-label="Clear Chat"
+              @click="resetChat"
+            />
+          </UTooltip>
+          <UTooltip :text="aiChat.texts.close">
+            <UButton
+              :icon="aiChat.icons.close"
+              color="neutral"
+              variant="ghost"
+              size="sm"
+              class="text-muted hover:text-highlighted"
+              aria-label="Close Chat Panel"
+              @click="isOpen = false"
+            />
+          </UTooltip>
+        </div>
+      </div>
+
+      <div class="min-h-0 flex-1 overflow-y-auto">
+        <UChatMessages
+          v-if="chat.messages.length > 0"
+          should-auto-scroll
+          :messages="chat.messages"
+          compact
+          :status="chat.status"
+          :user="{ ui: { container: 'pb-2', content: 'text-sm' } }"
+          :ui="{ indicator: '*:bg-accented', root: 'h-auto!' }"
+          class="px-4 py-4"
+        >
+          <template #content="{ message }">
+            <div class="flex flex-col gap-2">
+              <template
+                v-for="(part, index) in message.parts"
+                :key="`${message.id}-${part.type}-${index}${'state' in part ? `-${part.state}` : ''}`"
+              >
+                <AiChatReasoning v-if="part.type === 'reasoning'" :text="part.text" :is-streaming="part.state !== 'done'" />
+
+                <MDCCached
+                  v-else-if="part.type === 'text'"
+                  :value="part.text"
+                  :cache-key="`${message.id}-${index}`"
+                  :components="components"
+                  :parser-options="{ highlight: false }"
+                  class="*:first:mt-0 *:last:mb-0"
+                />
+
+                <template v-else-if="part.type === 'data-tool-calls'">
+                  <AiChatToolCall
+                    v-for="tool in (part as any).data.tools"
+                    :key="`${tool.toolCallId}-${JSON.stringify(tool.args)}`"
+                    :text="getToolLabel(tool.toolName, tool.args)"
+                    :is-loading="false"
+                  />
+                </template>
+              </template>
+              <UButton
+                v-if="chat.status === 'streaming' && message.id === lastMessage?.id"
+                class="px-0"
+                color="neutral"
+                variant="link"
+                size="sm"
+                :label="aiChat.texts.loading"
+                loading
+                :loading-icon="aiChat.icons.loading"
+              />
+            </div>
+          </template>
+        </UChatMessages>
+
+        <div
+          v-else
+          class="p-4"
+        >
+          <div
+            v-if="!faqQuestions?.length"
+            class="flex h-full flex-col items-center justify-center py-12 text-center"
+          >
+            <div class="mb-4 flex size-12 items-center justify-center rounded-full bg-primary/10">
+              <UIcon
+                name="i-lucide-message-circle-question"
+                class="size-6 text-primary"
+              />
+            </div>
+            <h3 class="mb-2 text-base font-medium text-highlighted">
+              {{ aiChat.texts.askAnything }}
+            </h3>
+            <p class="max-w-xs text-sm text-muted">
+              {{ aiChat.texts.askMeAnythingDescription }}
+            </p>
+          </div>
+
+          <template v-else>
+            <p class="mb-4 text-sm font-medium text-muted">
+              {{ aiChat.texts.faq }}
+            </p>
+
+            <AiChatSlideoverFaq :faq-questions="faqQuestions" @ask-question="askQuestion" />
+          </template>
+        </div>
+      </div>
+
+      <div class="w-full shrink-0 p-3">
+        <UChatPrompt
+          v-model="input"
+          :rows="2"
+          class="text-sm"
+          variant="subtle"
+          :placeholder="aiChat.texts.placeholder"
+          :ui="{
+            root: 'shadow-none!',
+            body: '*:p-0! *:rounded-none!'
+          }"
+          @submit="handleSubmit"
+        >
+          <template #footer>
+            <div class="hidden items-center divide-x divide-muted/50 sm:flex">
+              <AiChatModelSelect v-model="model" />
+              <div class="flex gap-1 justify-between items-center px-1 text-xs text-muted">
+                <span>{{ aiChat.texts.lineBreak }}</span>
+                <UKbd value="shift" />
+                <UKbd value="enter" />
+              </div>
+            </div>
+
+            <UChatPromptSubmit
+              class="ml-auto"
+              size="xs"
+              :status="chat.status"
+              @stop="chat.stop()"
+              @reload="chat.regenerate()"
+            />
+          </template>
+        </UChatPrompt>
+      </div>
+    </div>
+  </DefineChatContent>
+
+  <aside
+    v-if="!isMobile"
+    class="fixed top-0 z-50 h-dvh overflow-hidden border-l border-muted/50 bg-default/95 backdrop-blur-xl transition-[right,width] duration-200 ease-linear will-change-[right,width]"
+    :style="{
+      width: `${panelWidth}px`,
+      right: isOpen ? '0' : `-${panelWidth}px`
+    }"
+  >
+    <div
+      class="h-full transition-[width] duration-200 ease-linear"
+      :style="{ width: `${panelWidth}px` }"
+    >
+      <ReuseChatContent :show-expand-button="true" />
+    </div>
+  </aside>
+
+  <USlideover
+    v-else
+    v-model:open="isOpen"
+    title=" "
+    description=" "
+    side="right"
+    :ui="{
+      content: 'ring-0 bg-default'
+    }"
+  >
+    <template #content>
+      <ReuseChatContent :show-expand-button="false" />
+    </template>
+  </USlideover>
+</template>

package/modules/ai-chat/runtime/components/AiChatPreStream.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { ShikiCachedRenderer } from 'shiki-stream/vue'
+import { useHighlighter } from '../composables/useHighlighter'
 
 const colorMode = useColorMode()
 const highlighter = await useHighlighter()

package/modules/ai-chat/runtime/components/AiChatReasoning.vue

@@ -12,7 +12,7 @@ const { isStreaming = false } = defineProps<{
 }>()
 
 const open = ref(false)
-const { ui } = useAppConfig()
+const { ui, aiChat } = useAppConfig()
 
 watch(() => isStreaming, () => {
   open.value = isStreaming
@@ -33,11 +33,11 @@ function cleanMarkdown(text: string): string {
       class="p-0 group"
       color="neutral"
       variant="link"
-      :trailing-icon="ui.icons.chevronDown"
+      :trailing-icon="aiChat.icons.streaming || ui.icons.chevronDown"
       :ui="{
         trailingIcon: text.length > 0 ? 'group-data-[state=open]:rotate-180 transition-transform duration-200' : 'hidden'
       }"
-      :label="isStreaming ? '思考中...' : '思考过程'"
+      :label="isStreaming ? aiChat.texts.streaming : aiChat.texts.streamed"
     />
 
     <template #content>

package/modules/ai-chat/runtime/components/AiChatSlideoverFaq.vue

@@ -1,8 +1,5 @@
 <script lang="ts" setup>
-export interface FaqCategory {
-  category: string
-  items: string[]
-}
+import type { FaqCategory } from '../types'
 
 defineProps<{
   /**
@@ -23,7 +20,7 @@ defineEmits<{
       :key="category.category"
       class="flex flex-col gap-1.5"
     >
-      <h4 class="text-xs font-medium text-dimmed uppercase tracking-wide">
+      <h4 class="text-xs font-medium text-muted uppercase tracking-wide">
         {{ category.category }}
       </h4>
       <div class="flex flex-col">

package/modules/ai-chat/runtime/composables/useAIChat.ts

@@ -1,10 +1,47 @@
 import type { UIMessage } from 'ai'
+import { useMediaQuery } from '@vueuse/core'
+import type { FaqCategory, FaqQuestions } from '../types'
+
+function normalizeFaqQuestions(questions: FaqQuestions): FaqCategory[] {
+  if (!questions || (Array.isArray(questions) && questions.length === 0)) {
+    return []
+  }
+
+  if (typeof questions[0] === 'string') {
+    return [{
+      category: '问题',
+      items: questions as string[]
+    }]
+  }
+
+  return questions as FaqCategory[]
+}
+
+const PANEL_WIDTH_COMPACT = 360
+const PANEL_WIDTH_EXPANDED = 520
 
 export function useAIChat() {
+  const config = useRuntimeConfig()
+  const appConfig = useAppConfig()
+  const isEnabled = computed(() => config.public.aiChat?.enabled ?? false)
+
   const isOpen = useState('ai-chat-open', () => false)
+  const isExpanded = useState('ai-chat-expanded', () => false)
   const messages = useState<UIMessage[]>('ai-chat-messages', () => [])
   const pendingMessage = useState<string | undefined>('ai-chat-pending', () => undefined)
 
+  const isMobile = useMediaQuery('(max-width: 767px)')
+  const panelWidth = computed(() => isExpanded.value ? PANEL_WIDTH_EXPANDED : PANEL_WIDTH_COMPACT)
+  const shouldPushContent = computed(() => !isMobile.value && isOpen.value)
+
+  const faqQuestions = computed<FaqCategory[]>(() => {
+    const aiChatConfig = appConfig.aiChat
+    const faqConfig = aiChatConfig?.faqQuestions
+    if (!faqConfig) return []
+
+    return normalizeFaqQuestions(faqConfig)
+  })
+
   function open(initialMessage?: string, clearPrevious = false) {
     if (clearPrevious) {
       messages.value = []
@@ -32,14 +69,25 @@ export function useAIChat() {
     messages.value = []
   }
 
+  function toggleExpanded() {
+    isExpanded.value = !isExpanded.value
+  }
+
   return {
+    isEnabled,
     isOpen,
+    isExpanded,
+    isMobile,
+    panelWidth,
+    shouldPushContent,
     messages,
     pendingMessage,
+    faqQuestions,
     open,
     clearPending,
     close,
     toggle,
+    toggleExpanded,
     clearMessages
   }
 }