@movk/nuxt-docs 1.8.0 → 1.9.0

package/README.md

@@ -20,6 +20,10 @@
 
 ### 🤖 AI 增强体验
 
+<div style="padding: 40px 0; display: flex; justify-content: center;">
+  <img src="https://docs.mhaibaraai.cn/ai/AiChat.png" alt="AiChat" width="400">
+</div>
+
 - **AI 聊天助手** - 内置智能文档助手，基于 Vercel AI SDK 支持多种 LLM 模型（Mistral、Qwen、OpenRouter）
 - **MCP Server 支持** - 集成 Model Context Protocol 服务器，为 AI 助手提供结构化的文档访问能力
 - **LLM 优化** - 通过 `nuxt-llms` 模块自动生成 `llms.txt` 和 `llms-full.txt`，为 AI 工具提供优化的文档索引

package/app/app.config.ts

@@ -108,8 +108,7 @@ export default defineAppConfig({
       streaming: 'i-lucide-chevron-down',
       providers: {
         mistral: 'i-simple-icons-mistralai',
-        kwaipilot: 'i-lucide-wand',
-        zai: 'i-lucide-wand'
+        kwaipilot: 'i-lucide-wand'
       }
     }
   }

package/app/components/content/Mermaid.vue

@@ -81,10 +81,11 @@ const diagramRef = ref<HTMLElement | null>(null)
 const isRendered = ref(false)
 const hasError = ref(false)
 const errorMessage = ref('')
+const hasBeenVisible = ref(false)
 
 const [isFullscreen, toggleFullscreen] = useToggle(false)
 const { copy, copied } = useClipboard({ source: () => props.code })
-const isVisible = useElementVisibility(containerRef)
+const isVisible = useElementVisibility(containerRef, { threshold: 0.1 })
 
 async function renderMermaid() {
   if (!props.code || isRendered.value || !diagramRef.value) return
@@ -127,7 +128,11 @@ async function reRender() {
 watch(
   [isVisible, diagramRef],
   ([visible, el]) => {
-    if (visible && el && !isRendered.value) {
+    // 记录曾经可见状态，避免快速滚动时错过渲染
+    if (visible) {
+      hasBeenVisible.value = true
+    }
+    if (hasBeenVisible.value && el && !isRendered.value) {
       renderMermaid()
     }
   },

package/app/composables/useToolCall.ts

@@ -1,7 +1,9 @@
 export function useToolCall() {
   const tools: Record<string, string | ((args: any) => string)> = {
     'list-pages': '列出所有文档页面',
-    'get-page': (args: any) => `检索 ${args?.path || '页面'}`
+    'get-page': (args: any) => `检索 ${args?.path || '页面'}`,
+    'list-examples': '列出所有示例',
+    'get-example': (args: any) => `获取示例：${args?.exampleName || '示例'}`
   }
   return {
     tools

package/app/pages/docs/[...slug].vue

@@ -14,7 +14,7 @@ const { toc, github } = useAppConfig()
 const { data: page } = await useAsyncData(`docs-${kebabCase(route.path)}`, () => queryCollection('docs').path(route.path).first())
 
 if (!page.value) {
-  throw createError({ statusCode: 404, statusMessage: 'Page not found', fatal: true })
+  throw createError({ status: 404, statusText: 'Page not found', fatal: true })
 }
 
 const navigation = inject<Ref<ContentNavigationItem[]>>('navigation')

package/app/pages/index.vue

@@ -1,7 +1,7 @@
 <script setup lang="ts">
 const { data: page } = await useAsyncData('landing', () => queryCollection('landing').path('/').first())
 if (!page.value) {
-  throw createError({ statusCode: 404, statusMessage: 'Page not found', fatal: true })
+  throw createError({ status: 404, statusText: 'Page not found', fatal: true })
 }
 
 const title = page.value.seo?.title || page.value.title

package/app/templates/releases.vue

@@ -3,7 +3,7 @@ import type { ButtonProps } from '@nuxt/ui'
 
 const { data: page } = await useAsyncData('releases', () => queryCollection('releases').first())
 if (!page.value) {
-  throw createError({ statusCode: 404, statusMessage: 'Page not found', fatal: true })
+  throw createError({ status: 404, statusText: 'Page not found', fatal: true })
 }
 
 const title = page.value.seo?.title || page.value.title

package/content.config.ts

@@ -1,9 +1,8 @@
 import { existsSync } from 'node:fs'
 import { defineCollection, defineContentConfig } from '@nuxt/content'
 import { useNuxt } from '@nuxt/kit'
-import { asSeoCollection } from '@nuxtjs/seo/content'
 import { joinURL } from 'ufo'
-import { z } from 'zod/v4'
+import { z } from 'zod'
 
 const { options } = useNuxt()
 const cwd = joinURL(options.rootDir, 'content')
@@ -38,14 +37,14 @@ const PageHero = z.object({
 
 export default defineContentConfig({
   collections: {
-    landing: defineCollection(asSeoCollection({
+    landing: defineCollection({
       type: 'page',
       source: {
         cwd,
         include: 'index.md'
       }
-    })),
-    docs: defineCollection(asSeoCollection({
+    }),
+    docs: defineCollection({
       type: 'page',
       source: {
         cwd,
@@ -58,8 +57,8 @@ export default defineContentConfig({
           title: z.string().optional()
         })
       })
-    })),
-    releases: defineCollection(asSeoCollection({
+    }),
+    releases: defineCollection({
       type: 'page',
       source: {
         cwd,
@@ -71,6 +70,6 @@ export default defineContentConfig({
         releases: z.string(),
         hero: PageHero
       })
-    }))
+    })
   }
 })

package/modules/ai-chat/index.ts

@@ -22,7 +22,7 @@ export interface AiChatModuleOptions {
    */
   mcpPath?: string
   /**
-   * 通过 AI SDK Gateway 、OpenRouter 使用的 AI 模型
+   * 使用的 AI 模型
    */
   model?: string
   /**
@@ -46,7 +46,7 @@ export default defineNuxtModule<AiChatModuleOptions>({
     models: []
   },
   setup(options, nuxt) {
-    const hasApiKey = !!(process.env.AI_GATEWAY_API_KEY || process.env.OPENROUTER_API_KEY)
+    const hasApiKey = !!(process.env.AI_GATEWAY_API_KEY || process.env.OPENROUTER_API_KEY || process.env.ZHIPU_API_KEY)
 
     const { resolve } = createResolver(import.meta.url)
 
@@ -77,7 +77,7 @@ export default defineNuxtModule<AiChatModuleOptions>({
     }
 
     if (!hasApiKey) {
-      log.warn('[ai-chat] Module disabled: no AI_GATEWAY_API_KEY or OPENROUTER_API_KEY found')
+      log.warn('[ai-chat] Module disabled: no API key found in environment variables.')
       return
     }
 

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

@@ -1,5 +1,5 @@
 import { tool, stepCountIs, generateText } from 'ai'
-import { z } from 'zod/v4'
+import { z } from 'zod'
 
 function getSubAgentSystemPrompt(siteName: string) {
   return `您是 ${siteName} 的文档搜索代理。您的工作是从文档中查找并检索相关信息。

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

@@ -1,23 +1,29 @@
 import { createGateway } from '@ai-sdk/gateway'
 import { createOpenRouter } from '@openrouter/ai-sdk-provider'
+import { modelProviderRegistry } from './modelProviders'
+
+modelProviderRegistry.register('openrouter', ({ config, modelId }) => {
+  const openRouter = createOpenRouter({
+    apiKey: config.openRouterApiKey as string | undefined
+  })
+  return openRouter.chat(modelId)
+})
 
 /**
  * 获取 AI 模型实例
- * @param modelId - 模型标识符,格式为 "provider/model" 或 "model"
- * @returns AI SDK 模型实例
+ * 优先使用注册的提供商，否则回退到 AI Gateway
  */
 export function getModel(modelId: string) {
   const config = useRuntimeConfig()
+  const parsed = modelProviderRegistry.parseModelId(modelId)
 
-  // OpenRouter 模型:以 "openrouter/" 开头
-  if (modelId.startsWith('openrouter/')) {
-    const openRouter = createOpenRouter({
-      apiKey: config.openRouterApiKey as string | undefined
-    })
-    return openRouter.chat(modelId.replace('openrouter/', ''))
+  if (parsed) {
+    const factory = modelProviderRegistry.get(parsed.prefix)
+    if (factory) {
+      return factory({ config, modelId: parsed.modelId })
+    }
   }
 
-  // AI Gateway 模型(默认)
   const gateway = createGateway({
     apiKey: config.aiGatewayApiKey as string | undefined
   })

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

@@ -0,0 +1,34 @@
+import type { LanguageModel } from 'ai'
+
+export interface ModelProviderContext {
+  config: ReturnType<typeof useRuntimeConfig>
+  modelId: string
+}
+
+export type ModelProviderFactory = (context: ModelProviderContext) => LanguageModel
+
+/**
+ * 模型提供商注册表
+ */
+class ModelProviderRegistry {
+  private providers = new Map<string, ModelProviderFactory>()
+
+  register(prefix: string, factory: ModelProviderFactory): void {
+    this.providers.set(prefix, factory)
+  }
+
+  get(prefix: string): ModelProviderFactory | undefined {
+    return this.providers.get(prefix)
+  }
+
+  parseModelId(modelId: string): { prefix: string, modelId: string } | null {
+    const separatorIndex = modelId.indexOf('/')
+    if (separatorIndex === -1) return null
+    return {
+      prefix: modelId.slice(0, separatorIndex),
+      modelId: modelId.slice(separatorIndex + 1)
+    }
+  }
+}
+
+export const modelProviderRegistry = new ModelProviderRegistry()

package/modules/config.ts

@@ -1,8 +1,8 @@
 import { createResolver, defineNuxtModule } from '@nuxt/kit'
-import { join } from 'pathe'
 import { defu } from 'defu'
 import { getGitBranch, getGitEnv, getLocalGitInfo } from '../utils/git'
 import { getPackageJsonMetadata, inferSiteURL } from '../utils/meta'
+import { createComponentMetaExcludeFilters } from '../utils/component-meta'
 
 export default defineNuxtModule({
   meta: {
@@ -10,32 +10,32 @@ export default defineNuxtModule({
   },
   async setup(_options, nuxt) {
     const { resolve } = createResolver(import.meta.url)
+
+    nuxt.options.alias['#ai-chat'] = resolve('./ai-chat/runtime')
+
     const dir = nuxt.options.rootDir
     const url = inferSiteURL()
     const meta = await getPackageJsonMetadata(dir)
     const gitInfo = await getLocalGitInfo(dir) || getGitEnv()
-    const siteName = nuxt.options?.site?.name || meta.name || gitInfo?.name || ''
+    const siteName = meta.name || gitInfo?.name || ''
+
+    nuxt.options.site = defu(nuxt.options.site, {
+      url,
+      name: siteName,
+      debug: false
+    })
 
     nuxt.options.llms = defu(nuxt.options.llms, {
       domain: url || 'https://example.com',
       title: siteName,
       description: meta.description || '',
+      contentRawMarkdown: false as const,
       full: {
         title: siteName,
         description: meta.description || ''
       }
     })
 
-    nuxt.options.site = defu(nuxt.options.site, {
-      url,
-      name: siteName,
-      debug: false
-    })
-
-    nuxt.options.robots = defu(nuxt.options.robots, {
-      sitemap: url ? `${url.replace(/\/$/, '')}/sitemap.xml` : undefined
-    })
-
     nuxt.options.appConfig.header = defu(nuxt.options.appConfig.header, {
       title: siteName
     })
@@ -59,34 +59,16 @@ export default defineNuxtModule({
     })
 
     const layerPath = resolve('..')
-    const allowedComponents = [
-      resolve('../app/components/content/CommitChangelog.vue'),
-      resolve('../app/components/content/ComponentEmits.vue'),
-      resolve('../app/components/content/ComponentExample.vue'),
-      resolve('../app/components/content/ComponentProps.vue'),
-      resolve('../app/components/content/ComponentSlots.vue'),
-      resolve('../app/components/content/PageLastCommit.vue'),
-      resolve('../app/components/content/Mermaid.vue'),
-      resolve('./ai-chat/runtime/components/AiChatToolCall.vue'),
-      resolve('./ai-chat/runtime/components/AiChatReasoning.vue'),
-      resolve('./ai-chat/runtime/components/AiChatSlideoverFaq.vue'),
-      resolve('./ai-chat/runtime/components/AiChatPreStream.vue')
-    ]
-    const userComponentPaths = [
-      join(dir, 'app/components'),
-      join(dir, 'components'),
-      join(dir, 'docs/app/components'),
-      join(dir, 'templates/*/app/components')
-    ]
 
     // @ts-ignore - component-meta is not typed
     nuxt.hook('component-meta:extend', (options: any) => {
+      const userInclude = (nuxt.options.componentMeta && typeof nuxt.options.componentMeta === 'object')
+        ? nuxt.options.componentMeta.include || []
+        : []
+
       options.exclude = [
         ...(options.exclude || []),
-        ({ filePath }: { filePath: string }) =>
-          filePath.startsWith(layerPath) && !allowedComponents.includes(filePath),
-        ({ filePath }: { filePath: string }) =>
-          userComponentPaths.some(path => filePath.startsWith(path))
+        ...createComponentMetaExcludeFilters(resolve, dir, layerPath, userInclude)
       ]
     })
   }

package/modules/css.ts

@@ -44,6 +44,8 @@ export default defineNuxtModule({
       }
     })
 
-    nuxt.options.css.unshift(cssTemplate.dst)
+    if (Array.isArray(nuxt.options.css)) {
+      nuxt.options.css.unshift(cssTemplate.dst)
+    }
   }
 })

package/nuxt.config.ts

@@ -12,10 +12,10 @@ export default defineNuxtConfig({
     '@nuxt/image',
     '@nuxt/a11y',
     '@nuxtjs/mcp-toolkit',
-    '@nuxtjs/seo',
     '@vueuse/nuxt',
     'nuxt-component-meta',
     'nuxt-llms',
+    'nuxt-og-image',
     'motion-v/nuxt',
     () => {
       extendViteConfig((config) => {
@@ -94,8 +94,8 @@ export default defineNuxtConfig({
     metaFields: {
       type: false,
       props: true,
-      slots: 'no-schema' as const,
-      events: 'no-schema' as const,
+      slots: 'no-schema',
+      events: 'no-schema',
       exposed: false
     },
     exclude: [
@@ -134,8 +134,5 @@ export default defineNuxtConfig({
       'Inter:400',
       'Inter:700'
     ]
-  },
-  sitemap: {
-    zeroRuntime: true
   }
 })

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@movk/nuxt-docs",
   "type": "module",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "private": false,
   "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>",
@@ -28,9 +28,9 @@
     "README.md"
   ],
   "dependencies": {
-    "@ai-sdk/gateway": "^3.0.17",
-    "@ai-sdk/mcp": "^1.0.11",
-    "@ai-sdk/vue": "^3.0.42",
+    "@ai-sdk/gateway": "^3.0.22",
+    "@ai-sdk/mcp": "^1.0.13",
+    "@ai-sdk/vue": "^3.0.48",
     "@iconify-json/lucide": "^1.2.86",
     "@iconify-json/ph": "^1.2.2",
     "@iconify-json/simple-icons": "^1.2.67",
@@ -40,36 +40,36 @@
     "@nuxt/a11y": "^1.0.0-alpha.1",
     "@nuxt/content": "^3.11.0",
     "@nuxt/image": "^2.0.0",
-    "@nuxt/kit": "^4.2.2",
-    "@nuxt/ui": "^4.3.0",
+    "@nuxt/kit": "^4.3.0",
+    "@nuxt/ui": "^4.4.0",
     "@nuxtjs/mcp-toolkit": "^0.6.2",
-    "@nuxtjs/seo": "^3.3.0",
     "@octokit/rest": "^22.0.1",
     "@openrouter/ai-sdk-provider": "^2.0.0",
     "@vercel/analytics": "^1.6.1",
     "@vercel/speed-insights": "^1.3.1",
     "@vueuse/core": "^14.1.0",
     "@vueuse/nuxt": "^14.1.0",
-    "ai": "^6.0.42",
+    "ai": "^6.0.48",
     "defu": "^6.1.4",
-    "dompurify": "^3.2.6",
+    "dompurify": "^3.3.1",
     "exsolve": "^1.0.8",
     "git-url-parse": "^16.1.0",
     "mermaid": "^11.12.2",
     "motion-v": "^1.9.0",
-    "nuxt": "^4.2.2",
+    "nuxt": "^4.3.0",
     "nuxt-component-meta": "^0.17.1",
     "nuxt-llms": "^0.2.0",
+    "nuxt-og-image": "^5.1.13",
     "ohash": "^2.0.11",
     "pathe": "^2.0.3",
     "pkg-types": "^2.3.0",
-    "prettier": "^3.8.0",
+    "prettier": "^3.8.1",
     "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.3",
-    "zod": "^4.3.5"
+    "zod": "^4.3.6"
   }
 }

package/server/api/component-example.get.ts

@@ -10,8 +10,8 @@ export default defineEventHandler((event) => {
     const component = components[pascalCase(componentName)]
     if (!component) {
       throw createError({
-        statusMessage: 'Example not found!',
-        statusCode: 404
+        statusText: 'Example not found!',
+        status: 404
       })
     }
     return component

package/server/api/github/commits.get.ts

@@ -10,8 +10,8 @@ export default defineCachedEventHandler(async (event) => {
 
   if (!paths.length || !paths[0]) {
     throw createError({
-      statusCode: 400,
-      statusMessage: 'Path is required'
+      status: 400,
+      statusText: 'Path is required'
     })
   }
 
@@ -19,8 +19,8 @@ export default defineCachedEventHandler(async (event) => {
 
   if (!github || typeof github === 'boolean') {
     throw createError({
-      statusCode: 500,
-      statusMessage: 'GitHub configuration is not available'
+      status: 500,
+      statusText: 'GitHub configuration is not available'
     })
   }
 

package/server/api/github/last-commit.get.ts

@@ -8,8 +8,8 @@ export default defineCachedEventHandler(async (event) => {
   const { path } = getQuery(event) as { path: string }
   if (!path) {
     throw createError({
-      statusCode: 400,
-      statusMessage: 'Path is required'
+      status: 400,
+      statusText: 'Path is required'
     })
   }
 
@@ -17,8 +17,8 @@ export default defineCachedEventHandler(async (event) => {
 
   if (!github || typeof github === 'boolean') {
     throw createError({
-      statusCode: 500,
-      statusMessage: 'GitHub configuration is not available'
+      status: 500,
+      statusText: 'GitHub configuration is not available'
     })
   }
 

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

@@ -0,0 +1,19 @@
+import { z } from 'zod'
+
+export default defineMcpTool({
+  description: '检索特定的 UI 示例实现代码和详细信息',
+  inputSchema: {
+    exampleName: z.string().describe('示例名称（PascalCase）')
+  },
+  cache: '30m',
+  async handler({ exampleName }) {
+    try {
+      const result = await $fetch<{ code: string }>(`/api/component-example/${exampleName}.json`)
+      return {
+        content: [{ type: 'text' as const, text: result.code }]
+      }
+    } catch {
+      return errorResult(`示例 '${exampleName}' 未找到。使用 list_examples 工具查看所有可用示例。`)
+    }
+  }
+})

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

@@ -1,9 +1,9 @@
-import { z } from 'zod/v4'
+import { z } from 'zod'
 import { queryCollection } from '@nuxt/content/server'
 import { inferSiteURL } from '../../../utils/meta'
 
 export default defineMcpTool({
-  description: `检索特定文档页面的完整内容和详细信息。
+  description: `检索特定文档页面的完整内容和详细信息，使用 \`sections\` 参数仅获取特定的 h2 部分以减少响应大小。'
 
 何时使用：当你知道文档页面的确切路径时使用。常见用例：
 - 用户请求特定页面：「显示入门指南」→ /docs/getting-started
@@ -15,10 +15,11 @@ export default defineMcpTool({
 
 工作流程：此工具返回完整的页面内容，包括标题、描述和完整的 markdown。当你需要从特定文档页面提供详细答案或代码示例时使用。`,
   inputSchema: {
-    path: z.string().describe('从 list-pages 获取或用户提供的页面路径（例如 /docs/getting-started/installation）')
+    path: z.string().describe('从 list-pages 获取或用户提供的页面路径（例如 /docs/getting-started/installation）'),
+    sections: z.array(z.string()).optional().describe('要返回的特定 h2 部分标题（例如 ["Usage","API"]）。如果省略，则返回完整文档。')
   },
-  cache: '1h',
-  handler: async ({ path }) => {
+  cache: '30m',
+  handler: async ({ path, sections }) => {
     const event = useEvent()
     const siteUrl = import.meta.dev ? 'http://localhost:3000' : inferSiteURL()
 
@@ -35,10 +36,17 @@ export default defineMcpTool({
         }
       }
 
-      const content = await $fetch<string>(`/raw${path}.md`, {
+      const fullContent = await $fetch<string>(`/raw${path}.md`, {
         baseURL: siteUrl
       })
 
+      let content = fullContent
+
+      // If sections are specified, extract only those sections
+      if (sections && sections.length > 0) {
+        content = extractSections(fullContent, sections)
+      }
+
       const result = {
         title: page.title,
         path: page.path,
@@ -58,3 +66,64 @@ export default defineMcpTool({
     }
   }
 })
+
+/**
+ * Extract specific sections from markdown content based on h2 headings
+ */
+function extractSections(markdown: string, sectionTitles: string[]): string {
+  const lines = markdown.split('\n')
+  const result: string[] = []
+
+  // Normalize section titles for matching
+  const normalizedTitles = sectionTitles.map(t => t.toLowerCase().trim())
+
+  // Always include title (h1) and description (first blockquote)
+  let inHeader = true
+  for (const line of lines) {
+    if (inHeader) {
+      result.push(line)
+      // Stop after the description blockquote
+      if (line.startsWith('>') && result.length > 1) {
+        result.push('')
+        inHeader = false
+      }
+      continue
+    }
+    break
+  }
+
+  // Find and extract requested sections
+  let currentSection: string | null = null
+  let sectionContent: string[] = []
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (!line) continue
+
+    // Check for h2 heading
+    if (line.startsWith('## ')) {
+      // Save previous section if it was requested
+      if (currentSection && normalizedTitles.includes(currentSection.toLowerCase())) {
+        result.push(...sectionContent)
+        result.push('')
+      }
+
+      // Start new section
+      currentSection = line.replace('## ', '').trim()
+      sectionContent = [line]
+      continue
+    }
+
+    // Add line to current section
+    if (currentSection) {
+      sectionContent.push(line)
+    }
+  }
+
+  // Don't forget the last section
+  if (currentSection && normalizedTitles.includes(currentSection.toLowerCase())) {
+    result.push(...sectionContent)
+  }
+
+  return result.join('\n').trim()
+}

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

@@ -0,0 +1,14 @@
+// @ts-expect-error - no types available
+import components from '#component-example/nitro'
+
+export default defineMcpTool({
+  description: '列出所有可用的 UI 示例和代码演示',
+  cache: '1h',
+  handler() {
+    const examples = Object.entries<{ pascalName: string }>(components).map(([_key, value]) => {
+      return value.pascalName
+    })
+
+    return jsonResult(examples)
+  }
+})

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

@@ -19,7 +19,7 @@ export default defineMcpTool({
 - path：用于 get-page 的确切路径
 - description：页面内容的简要摘要
 - url：完整 URL 供参考`,
-  cache: '1h',
+  cache: '30m',
   handler: async () => {
     const event = useEvent()
     const siteUrl = import.meta.dev ? 'http://localhost:3000' : getRequestURL(event).origin