内置 AI 聊天助手

概述

一个提供基于 MCP（模型上下文协议）工具的 AI 聊天界面的 Nuxt 模块。

快速开始

Movk Nuxt Docs 已内置 AI Chat 模块。要启用该模块，请进行以下配置：

export default defineNuxtConfig({
  extends: ['@movk/nuxt-docs'],
  aiChat: {
    model: 'zai/glm-4.7',
    models: [
      'zai/glm-4.7',
      'anthropic/claude-sonnet-4.6',
      'google/gemini-2.5-flash'
    ],
  }
})

export default defineAppConfig({
  aiChat: {
    floatingInput: true,
    explainWithAi: true,
    faqQuestions: [
      {
        category: '快速开始',
        items: ['如何安装？', '如何配置？'],
      },
      {
        category: '进阶使用',
        items: ['如何自定义？'],
      },
    ],
    shortcuts: {
      focusInput: 'meta_i'
    },
    texts: {
      title: 'AI 助手',
      placeholder: '输入你的问题...',
      // ... 更多文本配置
    }
  }
})

# AI Gateway:单 key 代理多家（推荐）
AI_GATEWAY_API_KEY=your-gateway-key

# 或直连内置提供商:按需配置，对应前缀绕过 Gateway 直连官方 SDK
DEEPSEEK_API_KEY=your-deepseek-key
ALIBABA_API_KEY=your-alibaba-key
ZHIPU_API_KEY=your-zhipu-key

自动集成

默认情况下，以下功能会自动启用：

• AI Chat 触发按钮：在页面右侧显示，点击打开 AI 助手面板
• 浮动输入框：在文档页面底部显示（可通过 appConfig.aiChat.floatingInput 控制）
• AI 解释按钮：在文档侧边栏显示（可通过 appConfig.aiChat.explainWithAi 控制）

手动集成（可选）

如果需要在自定义页面中使用 AI Chat 组件：

<template>
  <div>
    <AiChat />
    <AiChatPanel />
  </div>
</template>

浮动输入框

浮动输入框默认已集成在文档页面底部。如需在自定义页面中使用：

<template>
  <div>
    <Teleport to="body">
      <ClientOnly>
        <AiChatPanel />
        <AiChatFloatingInput />
      </ClientOnly>
    </Teleport>
  </div>
</template>

编程式控制

使用 useAIChat 组合式函数来控制聊天：

<script setup>
const {
  isEnabled,
  isOpen,
  messages,
  toggleChat,
  open
} = useAIChat()

// 打开聊天并发送初始消息
open('如何安装这个模块？')

// 切换聊天可见性
toggle()
</script>

自定义

自定义模型提供商

import { modelProviderRegistry } from '#ai-chat/server/utils/modelProviders'
import { createAnthropic } from '@ai-sdk/anthropic'

export default defineNitroPlugin(() => {
  // 覆盖默认提供商配置
  modelProviderRegistry.register('anthropic', ({ config, modelId }) => {
    const anthropic = createAnthropic({
      apiKey: config.anthropicApiKey,
      // 自定义配置...
    })
    return anthropic(modelId)
  })
})

配置环境变量：

ANTHROPIC_API_KEY=your_api_key

内置提供商

配置对应环境变量后，匹配前缀的模型会直连官方 SDK；未命中任何前缀的模型回退至 AI Gateway。可选 <PROVIDER>_BASE_URL（如 ALIBABA_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 切到阿里云国内端点）覆盖端点/区域。在 server/plugins/ 中用 modelProviderRegistry.register(prefix, ...) 注册同名前缀可覆盖内置实现。

系统提示词

要自定义 AI 的行为，请创建编辑以下文件中的系统提示词： server/api/ai-chat.ts

样式

组件使用 Nuxt UI 和 Tailwind CSS 设计令牌。你可以通过修改组件文件或覆盖 UI 属性来自定义外观。

API

AiChat

最简单的集成方式，展示助手按钮。

AiChatFloatingInput

浮动输入框，位于视口下方。无需任何属性。

键盘快捷键：

• ⌘I / Ctrl+I - 聚焦输入框
• Escape - 失焦输入框
• Enter - 提交问题

AiChatModelSelect

模型选择下拉菜单，用于切换 AI 模型。无需任何属性。

AiChatPanel

完整的 AI 聊天面板界面。

特性：

• 可展开/折叠的侧边栏面板
• 自动推动主内容区域
• 内置消息历史和流式响应
• 支持代码高亮和 Markdown 渲染

AiChatDisabled

当 AI Chat 功能未启用时显示的禁用状态组件。

Composables

useAIChat()

对话状态管理，提供聊天界面的状态控制和消息管理功能。

返回值

useModels()

模型配置管理，控制可用的 AI 模型列表和当前选中的模型。

返回值

useHighlighter()

异步加载 Shiki 代码高亮器实例，用于代码块的语法高亮渲染。

返回值

返回一个 Promise，resolve 为配置好的 Shiki Highlighter 实例。

const highlighter = await useHighlighter()

// 使用示例
const html = highlighter.codeToHtml(code, {
  lang: 'typescript',
  theme: 'material-theme-palenight'
})

useToolCall(state, toolName, input)

AI 聊天工具调用的扩展点，允许自定义工具调用时显示的文本标签和图标。

当 AI 助手调用工具时，AiChatPanel 组件会调用此 composable 获取对应工具的显示信息。默认实现返回空对象，内置工具标签由组件自身处理。通过在应用层覆盖此 composable，可以为自定义工具添加显示支持。

参数

返回值

扩展自定义工具

在应用层创建同名 composable 覆盖默认实现：

import type { ToolState } from '#ai-chat/types'

export function useToolCall(state: ToolState, toolName: string, input: Record<string, string | undefined>) {
  const searchVerb = state === 'output-available' ? '已搜索' : '搜索中'
  const readVerb = state === 'output-available' ? '已读取' : '读取中'

  const toolMessage: Record<string, string> = {
    'search-api': `${searchVerb} API 文档`,
    'get-schema': `${readVerb} ${input.name || ''} 类型定义`,
  }

  const toolIcon: Record<string, string> = {
    'search-api': 'i-lucide-book-open',
    'get-schema': 'i-lucide-braces',
  }

  return {
    toolMessage,
    toolIcon,
  }
}

内置工具的默认处理

以下工具由 AiChatPanel 内置处理，无需在 useToolCall 中定义。默认处理已按当前项目内置的 MCP 工具裁剪，并由同一份配置同时生成显示文本与图标：