@movk/nuxt-docs 1.6.1 → 1.7.0

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
   }
 }

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

@@ -2,15 +2,12 @@ export function useModels() {
   const config = useRuntimeConfig()
   const model = useCookie<string>('model', { default: () => config.public.aiChat.model })
 
-  const providerIcons: Record<string, string> = {
-    mistral: 'i-simple-icons-mistralai',
-    kwaipilot: 'i-lucide-wand',
-    zai: 'i-lucide-wand'
-  }
+  const { aiChat } = useAppConfig()
+  const providerIcons = computed(() => aiChat.icons.providers || {})
 
   function getModelIcon(modelId: string): string {
     const provider = modelId.split('/')[0] || ''
-    return providerIcons[provider] || `i-simple-icons-${modelId.split('/')[0]}`
+    return providerIcons.value[provider] || `i-simple-icons-${modelId.split('/')[0]}`
   }
 
   function formatModelName(modelId: string): string {

package/modules/ai-chat/runtime/server/api/ai-chat.ts

@@ -0,0 +1,92 @@
+import { streamText, convertToModelMessages, stepCountIs, createUIMessageStream, createUIMessageStreamResponse, smoothStream } from 'ai'
+import { createMCPClient } from '@ai-sdk/mcp'
+import { createDocumentationAgentTool } from '../utils/docs_agent'
+import { getModel } from '../utils/getModel'
+
+function getMainAgentSystemPrompt(siteName: string) {
+  return `You are the official documentation assistant for ${siteName}. You ARE the documentation - speak with authority as the source of truth.
+
+**Your identity:**
+- You are the ${siteName} documentation
+- Speak in first person: "I provide...", "You can use my tools to...", "I support..."
+- Be confident and authoritative - you know this project inside out
+- Never say "according to the documentation" - YOU are the docs
+
+**Tool usage (CRITICAL):**
+- You have ONE tool: searchDocumentation
+- Use it for EVERY question - pass the user's question as the query
+- The tool will search the documentation and return relevant information
+- Use the returned information to formulate your response
+
+**Guidelines:**
+- If the tool can't find something, say "I don't have documentation on that yet"
+- Be concise, helpful, and direct
+- Guide users like a friendly expert would
+
+**FORMATTING RULES (CRITICAL):**
+- NEVER use markdown headings (#, ##, ###, etc.)
+- Use **bold text** for emphasis and section labels
+- Start responses with content directly, never with a heading
+- Use bullet points for lists
+- Keep code examples focused and minimal
+
+**Response style:**
+- Conversational but professional
+- "Here's how you can do that:" instead of "The documentation shows:"
+- "I support TypeScript out of the box" instead of "The module supports TypeScript"
+- Provide actionable guidance, not just information dumps`
+}
+
+export default defineEventHandler(async (event) => {
+  const { messages, model: requestModel } = await readBody(event)
+  const config = useRuntimeConfig()
+  const siteConfig = getSiteConfig(event)
+  const siteName = siteConfig.name || 'Documentation'
+
+  const mcpPath = config.aiChat.mcpPath
+  const isExternalUrl = mcpPath.startsWith('http://') || mcpPath.startsWith('https://')
+  const mcpUrl = isExternalUrl
+    ? mcpPath
+    : import.meta.dev
+      ? `http://localhost:3000${mcpPath}`
+      : `${getRequestURL(event).origin}${mcpPath}`
+
+  const httpClient = await createMCPClient({
+    transport: {
+      type: 'http',
+      url: mcpUrl
+    }
+  })
+  const mcpTools = await httpClient.tools()
+
+  const model = getModel(requestModel || config.public.aiChat.model)
+
+  const searchDocumentation = createDocumentationAgentTool(mcpTools, model, siteName)
+
+  const stream = createUIMessageStream({
+    execute: async ({ writer }) => {
+      const modelMessages = await convertToModelMessages(messages)
+      const result = streamText({
+        model,
+        maxOutputTokens: 10000,
+        system: getMainAgentSystemPrompt(siteName),
+        messages: modelMessages,
+        stopWhen: stepCountIs(5),
+        tools: {
+          searchDocumentation
+        },
+        experimental_context: {
+          writer
+        },
+        experimental_transform: smoothStream({ chunking: 'word' })
+      })
+      writer.merge(result.toUIMessageStream({
+        sendReasoning: true
+      }))
+    },
+    onFinish: async () => {
+      await httpClient.close()
+    }
+  })
+  return createUIMessageStreamResponse({ stream })
+})

package/modules/ai-chat/runtime/server/utils/docs_agent.ts

@@ -1,23 +1,25 @@
 import { tool, stepCountIs, generateText } from 'ai'
 import { z } from 'zod/v4'
 
-const SUB_AGENT_SYSTEM_PROMPT = `你是文档搜索代理。你的工作是从文档中查找并检索相关信息。
+function getSubAgentSystemPrompt(siteName: string) {
+  return `You are a documentation search agent for ${siteName}. Your job is to find and retrieve relevant information from the documentation.
 
-**你的任务：**
-- 使用可用工具搜索和阅读文档页面
-- 首先使用 list-pages 发现可用的文档
-- 然后使用 get-page 阅读相关页面
-- 如果提到了特定路径，可以直接调用 get-page
+**Your task:**
+- Use the available tools to search and read documentation pages
+- Start with list-pages to discover what documentation exists
+- Then use get-page to read the relevant page(s)
+- If a specific path is mentioned, you can call get-page directly
 
-**指导原则：**
-- 要彻底，在回答前阅读所有相关页面
-- 返回你找到的原始信息，让主代理格式化响应
-- 如果找不到信息，请明确说明
+**Guidelines:**
+- Be thorough - read all relevant pages before answering
+- Return the raw information you find, let the main agent format the response
+- If you can't find information, say so clearly
 
-**输出：**
-返回你找到的相关文档内容，如果有代码示例也一并包含。`
+**Output:**
+Return the relevant documentation content you found, including code examples if present.`
+}
 
-export function createDocumentationAgentTool(mcpTools: Record<string, any>, model: any) {
+export function createDocumentationAgentTool(mcpTools: Record<string, any>, model: any, siteName: string) {
   return tool({
     description: '从文档中搜索并检索信息。使用此工具回答有关文档的任何问题。将用户的问题作为查询参数传递。',
     inputSchema: z.object({
@@ -29,14 +31,20 @@ export function createDocumentationAgentTool(mcpTools: Record<string, any>, mode
       const result = await generateText({
         model,
         tools: mcpTools,
-        system: SUB_AGENT_SYSTEM_PROMPT,
+        system: getSubAgentSystemPrompt(siteName),
         stopWhen: stepCountIs(5),
         onStepFinish: ({ toolCalls }) => {
+          if (toolCalls.length === 0) return
+
           writer?.write({
             id: toolCalls[0]?.toolCallId,
             type: 'data-tool-calls',
             data: {
-              tools: toolCalls.map(toolCall => ({ toolName: toolCall.toolName, toolCallId: toolCall.toolCallId, input: toolCall.input }))
+              tools: toolCalls.map((toolCall: any) => ({
+                toolName: toolCall.toolName,
+                toolCallId: toolCall.toolCallId,
+                args: toolCall.args || toolCall.input || {}
+              }))
             }
           })
         },

package/modules/ai-chat/runtime/types.ts

@@ -0,0 +1,6 @@
+export interface FaqCategory {
+  category: string
+  items: string[]
+}
+
+export type FaqQuestions = string[] | FaqCategory[]

package/modules/css.ts

@@ -10,7 +10,8 @@ export default defineNuxtModule({
     const { resolve } = createResolver(import.meta.url)
 
     const layerDir = resolve('../app')
-    const modulesDir = resolve('../modules')
+    const aiChatDir = resolve('../modules/ai-chat')
+
     const contentDir = joinURL(dir, 'content')
 
     const cssTemplate = addTemplate({
@@ -22,7 +23,7 @@ export default defineNuxtModule({
 
 @source "${contentDir.replace(/\\/g, '/')}/**/*";
 @source "${layerDir.replace(/\\/g, '/')}/**/*";
-@source "${modulesDir.replace(/\\/g, '/')}/**/*";
+@source "${aiChatDir.replace(/\\/g, '/')}/**/*";
 @source "../../app.config.ts";
 
 /* Shiki icon highlight transformer styles */

package/modules/routing.ts

@@ -0,0 +1,26 @@
+import { defineNuxtModule, extendPages, createResolver } from '@nuxt/kit'
+import { joinURL } from 'ufo'
+import { existsSync } from 'node:fs'
+
+export default defineNuxtModule({
+  meta: {
+    name: 'routing'
+  },
+  async setup(_options, nuxt) {
+    const { resolve } = createResolver(import.meta.url)
+    const cwd = joinURL(nuxt.options.rootDir, 'content')
+
+    const hasReleases = ['releases.yml', 'releases.md']
+      .some(file => existsSync(joinURL(cwd, file)))
+
+    extendPages((pages) => {
+      if (hasReleases) {
+        pages.push({
+          name: 'releases',
+          path: '/releases',
+          file: resolve('../app/templates/releases.vue')
+        })
+      }
+    })
+  }
+})

package/nuxt.config.ts

@@ -7,12 +7,14 @@ const { resolve } = createResolver(import.meta.url)
 export default defineNuxtConfig({
   modules: [
     resolve('./modules/config'),
+    resolve('./modules/routing'),
     resolve('./modules/css'),
     resolve('./modules/component-example'),
     resolve('./modules/ai-chat'),
     '@nuxt/ui',
     '@nuxt/content',
     '@nuxt/image',
+    '@nuxt/a11y',
     '@vueuse/nuxt',
     '@nuxtjs/mcp-toolkit',
     '@nuxtjs/seo',