@movk/nuxt-docs 1.5.1 → 1.6.0

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

@@ -0,0 +1,41 @@
+<script lang="ts" setup>
+export interface FaqCategory {
+  category: string
+  items: string[]
+}
+
+defineProps<{
+  /**
+   * 聊天为空时显示的常见问题分类
+   */
+  faqQuestions: FaqCategory[]
+}>()
+
+defineEmits<{
+  (e: 'ask-question', question: string): void
+}>()
+</script>
+
+<template>
+  <div class="flex flex-col gap-5">
+    <div
+      v-for="category in faqQuestions"
+      :key="category.category"
+      class="flex flex-col gap-1.5"
+    >
+      <h4 class="text-xs font-medium text-dimmed uppercase tracking-wide">
+        {{ category.category }}
+      </h4>
+      <div class="flex flex-col">
+        <button
+          v-for="question in category.items"
+          :key="question"
+          class="text-left text-sm text-muted hover:text-highlighted py-1.5 transition-colors"
+          @click="$emit('ask-question', question)"
+        >
+          {{ question }}
+        </button>
+      </div>
+    </div>
+  </div>
+</template>

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

@@ -0,0 +1,31 @@
+<script setup lang="ts">
+import { motion } from 'motion-v'
+
+defineProps<{
+  /**
+   * 工具调用的标签文本
+   */
+  text: string
+  /**
+   * 为 true 时显示加载旋转圈
+   * @defaultValue false
+   */
+  isLoading?: boolean
+}>()
+</script>
+
+<template>
+  <motion.div
+    :initial="{ opacity: 0, y: 4 }"
+    :animate="{ opacity: 1, y: 0 }"
+    :transition="{ duration: 0.2 }"
+    class="flex items-center gap-2 px-2.5 py-1.5 rounded-lg bg-elevated/50 border border-default text-xs text-muted"
+  >
+    <UIcon
+      :name="isLoading ? 'i-lucide-loader-circle' : 'i-lucide-file-text'"
+      :class="[isLoading && 'animate-spin']"
+      class="size-4 shrink-0 text-muted"
+    />
+    <span class="truncate">{{ text }}</span>
+  </motion.div>
+</template>

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

@@ -0,0 +1,45 @@
+import type { UIMessage } from 'ai'
+
+export function useAIChat() {
+  const isOpen = useState('ai-chat-open', () => false)
+  const messages = useState<UIMessage[]>('ai-chat-messages', () => [])
+  const pendingMessage = useState<string | undefined>('ai-chat-pending', () => undefined)
+
+  function open(initialMessage?: string, clearPrevious = false) {
+    if (clearPrevious) {
+      messages.value = []
+    }
+
+    if (initialMessage) {
+      pendingMessage.value = initialMessage
+    }
+    isOpen.value = true
+  }
+
+  function clearPending() {
+    pendingMessage.value = undefined
+  }
+
+  function close() {
+    isOpen.value = false
+  }
+
+  function toggle() {
+    isOpen.value = !isOpen.value
+  }
+
+  function clearMessages() {
+    messages.value = []
+  }
+
+  return {
+    isOpen,
+    messages,
+    pendingMessage,
+    open,
+    clearPending,
+    close,
+    toggle,
+    clearMessages
+  }
+}

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

@@ -0,0 +1,58 @@
+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'
+  }
+
+  function getModelIcon(modelId: string): string {
+    const provider = modelId.split('/')[0] || ''
+    return providerIcons[provider] || `i-simple-icons-${modelId.split('/')[0]}`
+  }
+
+  function formatModelName(modelId: string): string {
+    const acronyms = ['gpt', 'llm', 'ai'] // words that should be uppercase
+
+    // 处理 OpenRouter 模型格式:openrouter/provider/model
+    if (modelId.startsWith('openrouter/')) {
+      const parts = modelId.split('/')
+      const model = parts[2] || parts[1] || modelId
+
+      // 提取模型名称(去除版本号和特殊标记)
+      const modelName = model.split(':')[0] || model
+
+      return modelName
+        .split('-')
+        .map((word) => {
+          const lowerWord = word.toLowerCase()
+          return acronyms.includes(lowerWord)
+            ? word.toUpperCase()
+            : word.charAt(0).toUpperCase() + word.slice(1)
+        })
+        .join(' ')
+    }
+
+    // 处理常规模型格式:provider/model
+    const modelName = modelId.split('/')[1] || modelId
+
+    return modelName
+      .split('-')
+      .map((word) => {
+        const lowerWord = word.toLowerCase()
+        return acronyms.includes(lowerWord)
+          ? word.toUpperCase()
+          : word.charAt(0).toUpperCase() + word.slice(1)
+      })
+      .join(' ')
+  }
+
+  return {
+    models: config.public.aiChat.models,
+    model,
+    formatModelName,
+    getModelIcon
+  }
+}

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

@@ -0,0 +1,31 @@
+export interface ToolLabelConfig {
+  toolName: string
+  label: string | ((args: any) => string)
+}
+
+export function useTools() {
+  const defaultLabels: Record<string, string | ((args: any) => string)> = {
+    'list-pages': '列出所有文档页面',
+    'get-page': (args: any) => `检索 ${args?.path || '页面'}`
+  }
+
+  /**
+   * 获取工具的显示标签
+   * @param toolName - 工具名称
+   * @param args - 工具参数
+   * @returns 工具的显示标签
+   */
+  function getToolLabel(toolName: string, args?: any): string {
+    const label = defaultLabels[toolName]
+
+    if (!label) {
+      return toolName
+    }
+
+    return typeof label === 'function' ? label(args) : label
+  }
+
+  return {
+    getToolLabel
+  }
+}

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

@@ -0,0 +1,84 @@
+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'
+
+const MAIN_AGENT_SYSTEM_PROMPT = `你是官方文档助手。你就是文档本身 - 以权威身份说话，成为真理的来源。
+
+**你的身份：**
+- 你是一位知识渊博且乐于助人的AI助手，是你所属模块的官方文档
+- 用第一人称说话："我提供...", "你可以使用我的工具...", "我支持..."
+- 要自信和权威 - 你深入了解这个模块的每一个细节
+- 永远不要说"根据文档" - 你就是文档
+
+**工具使用（关键）：**
+- 你有一个工具：searchDocumentation
+- 每个问题都要使用它 - 将用户的问题作为查询参数传递
+- 该工具会搜索文档并返回相关信息
+- 使用返回的信息来组织你的回答
+
+**指南：**
+- 如果工具找不到某些内容，说"我还没有关于这方面的文档"
+- 要简洁、有帮助、直接
+- 像一位友好的专家一样引导用户
+
+**格式规则（关键 - 必须严格遵守）：**
+- ❌ 禁止使用 markdown 标题（#、##、###、#### 等任何级别）
+- ✅ 使用 **粗体文本** 来标记章节和强调重点
+- ✅ 使用项目列表（- 或数字）组织内容
+- ✅ 直接开始回答，不要用标题作为开头
+- ✅ 保持代码示例简洁
+
+CRITICAL: Never output # ## ### #### or any heading syntax. Use **bold** instead.
+重要提醒：绝对不要输出 # ## ### #### 或任何标题语法。请用 **粗体** 代替。
+
+**响应风格：**
+- 对话式但专业
+- "你可以这样做："而不是"文档显示："
+- "我开箱即用地支持TypeScript"而不是"该模块支持TypeScript"
+- 提供可操作的指导，而不仅仅是信息转储`
+
+export default defineEventHandler(async (event) => {
+  const { messages, model: requestModel } = await readBody(event)
+  const config = useRuntimeConfig()
+
+  const mcpPath = config.aiChat.mcpPath
+  const httpClient = await createMCPClient({
+    transport: {
+      type: 'http',
+      url: import.meta.dev ? `http://localhost:3000${mcpPath}` : `${getRequestURL(event).origin}${mcpPath}`
+    }
+  })
+  const mcpTools = await httpClient.tools()
+
+  const model = getModel(requestModel || config.public.aiChat.model)
+
+  const searchDocumentation = createDocumentationAgentTool(mcpTools, model)
+
+  const stream = createUIMessageStream({
+    execute: async ({ writer }) => {
+      const modelMessages = await convertToModelMessages(messages)
+      const result = streamText({
+        model,
+        maxOutputTokens: 10000,
+        system: MAIN_AGENT_SYSTEM_PROMPT,
+        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

@@ -0,0 +1,49 @@
+import { tool, stepCountIs, generateText } from 'ai'
+import { z } from 'zod/v4'
+
+const SUB_AGENT_SYSTEM_PROMPT = `你是文档搜索代理。你的工作是从文档中查找并检索相关信息。
+
+**你的任务：**
+- 使用可用工具搜索和阅读文档页面
+- 首先使用 list-pages 发现可用的文档
+- 然后使用 get-page 阅读相关页面
+- 如果提到了特定路径，可以直接调用 get-page
+
+**指导原则：**
+- 要彻底，在回答前阅读所有相关页面
+- 返回你找到的原始信息，让主代理格式化响应
+- 如果找不到信息，请明确说明
+
+**输出：**
+返回你找到的相关文档内容，如果有代码示例也一并包含。`
+
+export function createDocumentationAgentTool(mcpTools: Record<string, any>, model: any) {
+  return tool({
+    description: '从文档中搜索并检索信息。使用此工具回答有关文档的任何问题。将用户的问题作为查询参数传递。',
+    inputSchema: z.object({
+      query: z.string().describe('要在文档中搜索的问题')
+    }),
+    execute: async ({ query }, executionOptions) => {
+      const writer = (executionOptions as any)?.experimental_context?.writer
+
+      const result = await generateText({
+        model,
+        tools: mcpTools,
+        system: SUB_AGENT_SYSTEM_PROMPT,
+        stopWhen: stepCountIs(5),
+        onStepFinish: ({ toolCalls }) => {
+          writer?.write({
+            id: toolCalls[0]?.toolCallId,
+            type: 'data-tool-calls',
+            data: {
+              tools: toolCalls.map(toolCall => ({ toolName: toolCall.toolName, toolCallId: toolCall.toolCallId, input: toolCall.input }))
+            }
+          })
+        },
+        prompt: query
+      })
+
+      return result.text
+    }
+  })
+}

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

@@ -0,0 +1,25 @@
+import { createGateway } from '@ai-sdk/gateway'
+import { createOpenRouter } from '@openrouter/ai-sdk-provider'
+
+/**
+ * 获取 AI 模型实例
+ * @param modelId - 模型标识符,格式为 "provider/model" 或 "model"
+ * @returns AI SDK 模型实例
+ */
+export function getModel(modelId: string) {
+  const config = useRuntimeConfig()
+
+  // OpenRouter 模型:以 "openrouter/" 开头
+  if (modelId.startsWith('openrouter/')) {
+    const openRouter = createOpenRouter({
+      apiKey: config.openRouterApiKey as string | undefined
+    })
+    return openRouter.chat(modelId.replace('openrouter/', ''))
+  }
+
+  // AI Gateway 模型(默认)
+  const gateway = createGateway({
+    apiKey: config.aiGatewayApiKey as string | undefined
+  })
+  return gateway(modelId)
+}

package/modules/css.ts

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

package/nuxt.config.ts

@@ -1,4 +1,4 @@
-import { createResolver } from '@nuxt/kit'
+import { createResolver, extendViteConfig } from '@nuxt/kit'
 import { defineNuxtConfig } from 'nuxt/config'
 import pkg from './package.json'
 
@@ -9,15 +9,29 @@ export default defineNuxtConfig({
     resolve('./modules/config'),
     resolve('./modules/css'),
     resolve('./modules/component-example'),
-    resolve('./modules/llms'),
+    resolve('./modules/ai-chat'),
     '@nuxt/ui',
     '@nuxt/content',
     '@nuxt/image',
     '@vueuse/nuxt',
+    '@nuxtjs/mcp-toolkit',
     '@nuxtjs/seo',
     'nuxt-component-meta',
     'motion-v/nuxt',
-    'nuxt-llms'
+    'nuxt-llms',
+    () => {
+      extendViteConfig((config) => {
+        config.optimizeDeps ||= {}
+        config.optimizeDeps.include ||= []
+        config.optimizeDeps.include.push(
+          '@nuxt/content > slugify',
+          'extend',
+          '@ai-sdk/gateway > @vercel/oidc'
+        )
+        config.optimizeDeps.include = config.optimizeDeps.include
+          .map(id => id.replace(/^@nuxt\/content > /, '@movk/nuxt-docs > @nuxt/content > '))
+      })
+    }
   ],
   app: {
     rootAttrs: {
@@ -30,7 +44,14 @@ export default defineNuxtConfig({
     build: {
       markdown: {
         highlight: {
-          langs: ['bash', 'ts', 'typescript', 'diff', 'vue', 'json', 'yml', 'css', 'mdc', 'blade', 'edge']
+          langs: ['bash', 'ts', 'typescript', 'diff', 'vue', 'json', 'yml', 'yaml', 'css', 'mdc', 'blade', 'edge']
+        },
+        remarkPlugins: {
+          'remark-mdc': {
+            options: {
+              autoUnwrap: true
+            }
+          }
         }
       }
     }
@@ -40,22 +61,14 @@ export default defineNuxtConfig({
       noApiRoute: false
     }
   },
-  ui: {
-    experimental: {
-      componentDetection: true
-    }
-  },
   runtimeConfig: {
     public: {
       version: pkg.version
     }
   },
   routeRules: {
-    ...process.env.NODE_ENV === 'development'
-      ? {
-          '/_llms-full.txt': { proxy: '/llms-full.txt' }
-        }
-      : {}
+    '/llms.txt': { isr: true },
+    '/llms-full.txt': { isr: true }
   },
   experimental: {
     typescriptPlugin: true,
@@ -69,23 +82,10 @@ export default defineNuxtConfig({
   compatibilityDate: 'latest',
   nitro: {
     prerender: {
-      routes: ['/', '/sitemap.xml', '/robots.txt', '/404.html'],
       crawlLinks: true,
       autoSubfolderIndex: false
     }
   },
-  vite: {
-    optimizeDeps: {
-      // See: https://cn.vite.dev/config/dep-optimization-options.html
-      include: [
-        '@nuxt/content > slugify',
-        'extend', // unified 所需（用于 @nuxt/content 的 markdown 处理）
-        'debug', // Babel 和开发工具所需
-        'tailwind-variants',
-        'tailwindcss/colors'
-      ]
-    }
-  },
   fonts: {
     families: [
       { name: 'Public Sans', provider: 'google', global: true },
@@ -100,18 +100,6 @@ export default defineNuxtConfig({
   icon: {
     provider: 'iconify'
   },
-  image: {
-    format: ['webp', 'jpeg', 'jpg', 'png', 'svg'],
-    provider: 'ipx'
-  },
-  linkChecker: {
-    report: {
-      publish: true,
-      html: true,
-      markdown: true,
-      json: true
-    }
-  },
   ogImage: {
     zeroRuntime: true,
     googleFontMirror: 'fonts.loli.net',

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@movk/nuxt-docs",
   "type": "module",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "private": false,
-  "description": "An elegant documentation theme for Nuxt, powered by Nuxt UI and Nuxt Content.",
+  "description": "Modern Nuxt 4 documentation theme with auto-generated component docs, AI chat assistant, MCP server, and complete developer experience optimization.",
   "author": "YiXuan <mhaibaraai@gmail.com>",
   "license": "MIT",
   "homepage": "https://docs.mhaibaraai.cn",
@@ -27,24 +27,31 @@
     "README.md"
   ],
   "dependencies": {
+    "@ai-sdk/gateway": "^3.0.10",
+    "@ai-sdk/mcp": "^1.0.5",
+    "@ai-sdk/vue": "^3.0.19",
     "@iconify-json/lucide": "^1.2.82",
-    "@iconify-json/simple-icons": "^1.2.63",
+    "@iconify-json/simple-icons": "^1.2.65",
     "@iconify-json/vscode-icons": "^1.2.37",
-    "@movk/core": "^1.0.3",
+    "@movk/core": "^1.1.0",
     "@nuxt/content": "^3.10.0",
     "@nuxt/image": "^2.0.0",
     "@nuxt/kit": "^4.2.2",
     "@nuxt/ui": "^4.3.0",
+    "@nuxtjs/mcp-toolkit": "^0.6.1",
     "@nuxtjs/seo": "^3.3.0",
     "@octokit/rest": "^22.0.1",
+    "@openrouter/ai-sdk-provider": "^1.5.4",
     "@vercel/analytics": "^1.6.1",
     "@vercel/speed-insights": "^1.3.1",
     "@vueuse/core": "^14.1.0",
     "@vueuse/nuxt": "^14.1.0",
+    "ai": "^6.0.19",
     "defu": "^6.1.4",
     "exsolve": "^1.0.8",
     "git-url-parse": "^16.1.0",
-    "motion-v": "^1.7.4",
+    "motion-v": "^1.7.6",
+    "nuxt": "^4.2.2",
     "nuxt-component-meta": "^0.16.0",
     "nuxt-llms": "^0.1.3",
     "ohash": "^2.0.11",
@@ -52,8 +59,11 @@
     "pkg-types": "^2.3.0",
     "prettier": "^3.7.4",
     "scule": "^1.3.0",
+    "shiki": "^3.21.0",
+    "shiki-stream": "^0.1.4",
     "shiki-transformer-color-highlight": "^1.0.0",
     "tailwindcss": "^4.1.18",
-    "ufo": "^1.6.1"
+    "ufo": "^1.6.2",
+    "zod": "^4.3.5"
   }
 }

package/server/mcp/tools/get-page.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod/v4'
+import { queryCollection } from '@nuxt/content/server'
+import { inferSiteURL } from '../../../utils/meta'
+
+export default defineMcpTool({
+  description: `检索特定文档页面的完整内容和详细信息。
+
+何时使用：当你知道文档页面的确切路径时使用。常见用例：
+- 用户请求特定页面：「显示入门指南」→ /docs/getting-started
+- 用户询问已知主题的专用页面
+- 你从 list-pages 找到了相关路径并想要完整内容
+- 用户引用了他们想要阅读的特定部分或指南
+
+何时不使用：如果你不知道确切路径并需要搜索/探索，请先使用 list-pages。
+
+工作流程：此工具返回完整的页面内容，包括标题、描述和完整的 markdown。当你需要从特定文档页面提供详细答案或代码示例时使用。`,
+  inputSchema: {
+    path: z.string().describe('从 list-pages 获取或用户提供的页面路径（例如 /docs/getting-started/installation）')
+  },
+  cache: '1h',
+  handler: async ({ path }) => {
+    const event = useEvent()
+    const siteUrl = import.meta.dev ? 'http://localhost:3000' : inferSiteURL()
+
+    try {
+      const page = await queryCollection(event, 'docs')
+        .where('path', '=', path)
+        .select('title', 'path', 'description')
+        .first()
+
+      if (!page) {
+        return {
+          content: [{ type: 'text', text: '页面未找到' }],
+          isError: true
+        }
+      }
+
+      const content = await $fetch<string>(`/raw${path}.md`, {
+        baseURL: siteUrl
+      })
+
+      const result = {
+        title: page.title,
+        path: page.path,
+        description: page.description,
+        content,
+        url: `${siteUrl}${page.path}`
+      }
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
+      }
+    } catch {
+      return {
+        content: [{ type: 'text', text: '获取页面失败' }],
+        isError: true
+      }
+    }
+  }
+})

package/server/mcp/tools/list-pages.ts

@@ -0,0 +1,49 @@
+import { queryCollection } from '@nuxt/content/server'
+
+export default defineMcpTool({
+  description: `列出所有可用的文档页面及其分类和基本信息。
+
+何时使用：当你需要探索或搜索某个主题的文档但不知道确切的页面路径时使用。常见场景：
+- 「查找关于 markdown 功能的文档」- 探索可用指南
+- 「显示所有入门指南」- 浏览入门内容
+- 「搜索高级配置选项」- 查找特定主题
+- 用户提出的一般性问题，未指定确切页面
+- 你需要了解整体文档结构
+
+何时不使用：如果你已经知道具体的页面路径（例如 "/docs/getting-started/installation"），请直接使用 get-page。
+
+工作流程：此工具返回页面标题、描述和路径。找到相关页面后，使用 get-page 检索符合用户需求的特定页面的完整内容。
+
+输出：返回包含以下内容的结构化列表：
+- title：可读的页面名称
+- path：用于 get-page 的确切路径
+- description：页面内容的简要摘要
+- url：完整 URL 供参考`,
+  cache: '1h',
+  handler: async () => {
+    const event = useEvent()
+    const siteUrl = import.meta.dev ? 'http://localhost:3000' : getRequestURL(event).origin
+
+    try {
+      const pages = await queryCollection(event, 'docs')
+        .select('title', 'path', 'description')
+        .all()
+
+      const result = pages.map(page => ({
+        title: page.title,
+        path: page.path,
+        description: page.description,
+        url: `${siteUrl}${page.path}`
+      }))
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
+      }
+    } catch {
+      return {
+        content: [{ type: 'text', text: '获取页面列表失败' }],
+        isError: true
+      }
+    }
+  }
+})

package/app/components/AdsCarbon.vue

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