---
title: "内置 AI 聊天助手"
description: "Movk Nuxt Docs 内置 AI Chat 模块，通过 MCP 工具与文档深度集成，支持流式响应、代码高亮、多模型切换和浮动输入框。了解如何配置模型、自定义提供商、编写系统提示词，以及使用 useAIChat 控制聊天状态。"
canonical_url: "https://docs.mhaibaraai.cn/docs/getting-started/ai-chat"
---
# 内置 AI 聊天助手

> Movk Nuxt Docs 内置 AI Chat 模块，通过 MCP 工具与文档深度集成，支持流式响应、代码高亮、多模型切换和浮动输入框。了解如何配置模型、自定义提供商、编写系统提示词，以及使用 useAIChat 控制聊天状态。

## 概述

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

## 快速开始

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

### 在 `nuxt.config.ts` 中添加模块配置：

```ts [nuxt.config.ts]
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-3-flash'
    ],
  }
})
```

模块配置选项：

| 选项 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `apiPath` | `string` | `/api/ai-chat` | 聊天 API 端点路径 |
| `mcpPath` | `string` | `/mcp` | MCP 服务器连接路径 |
| `model` | `string` | `-` | 模型标识符 |
| `models` | `string[]` | `[]` | 可用模型列表（格式为 "provider/model" 或 "model"） |

### 在 `app/app.config.ts` 中配置 AI Chat 功能：

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

> [!TIP]
> See: /docs/getting-started/configuration#ai-chat
> 
> 查看完整的 AI Chat 配置选项

> [!NOTE]
> 
> 启用多语言时，
> 
> faqQuestions
> 
>  可改为按 locale 分组的对象（如 
> 
> { 'zh-CN': [...], 'en': [...] }
> 
> ），面板会随当前语言切换。

### 将您的 API 密钥设置为环境变量：

```bash [.env]
# 必需:留空则模块禁用
AI_API_KEY=your-api-key

# 可选:OpenAI 兼容端点，留空则走 AI Gateway
# AI_BASE_URL=https://api.deepseek.com/v1
```

> [!TIP]
> 
> AI_API_KEY
> 
>  存在即可启用 AI Chat；缺失则模块禁用并在控制台记录一条消息。

### 推荐配置

**默认：AI Gateway**。只设 `AI_API_KEY`，一把 key 跨厂商，`models` 可以混搭不同厂商的模型，也就是上面快速开始里的示例配置。上手最省事，适合大多数场景。

**国内或需要直连：阿里云百炼**。百炼的兼容模式一把 key 就同时覆盖 Qwen、GLM、DeepSeek 三个系列，无需 Gateway 账号：

```bash [.env]
AI_API_KEY=your-dashscope-key
AI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
```

```ts [nuxt.config.ts]
aiChat: {
  model: 'alibaba/qwen3.7-plus',
  models: [
    'alibaba/qwen3.7-plus',
    'zai/glm-5.1',
    'deepseek/deepseek-v3.2'
  ]
}
```

这也是本站正在使用的配置。直连模式下前缀会在发请求前被剥掉，因此三个模型实际发送的是 `qwen3.7-plus`、`glm-5.1`、`deepseek-v3.2`，而前缀留下来负责在下拉框里渲染各家图标。更多端点地址与路由细节见 [模型路由](#%E6%A8%A1%E5%9E%8B%E8%B7%AF%E7%94%B1)。

## 自动集成

> [!TIP]
> 
> AI Chat 功能已内置在 Movk Nuxt Docs 中，无需手动添加组件。

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

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

### 手动集成（可选）

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

```vue
<template>
  <div>
    <AiChat />
    <AiChatPanel />
  </div>
</template>
```

> [!NOTE]
> 
> FAQ 问题现在在 
> 
> app/app.config.ts
> 
>  中配置，无需在组件中传递 props。

### 浮动输入框

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

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

> [!TIP]
> 
> 使用 
> 
> Teleport
> 
>  将浮动输入渲染到 body 级别，确保它无论在组件层次结构中如何变化都能固定在底部

### 编程式控制

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

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

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

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

## 自定义

### 自定义模型提供商

Layer 只内置 `@ai-sdk/openai`。要接入非 OpenAI 兼容协议的厂商，先在自己的项目里安装对应的 AI SDK 包，再按前缀注册：

> [!NOTE]
> See: https://ai-sdk.dev/providers/ai-sdk-providers/
> 
> 查看 AI SDK 支持的提供商列表

```ts [server/plugins/modelProviders.ts]
import { modelProviderRegistry } from '#ai-chat/server/utils/modelProviders'
import { createAnthropic } from '@ai-sdk/anthropic'

export default defineNitroPlugin(() => {
  // 注册 anthropic 前缀，anthropic/claude-sonnet-4.6 将命中这里
  modelProviderRegistry.register('anthropic', ({ modelId }) => {
    const anthropic = createAnthropic({
      apiKey: process.env.ANTHROPIC_API_KEY
      // 自定义配置...
    })
    return anthropic(modelId)
  })
})
```

配置环境变量：

```bash [.env]
ANTHROPIC_API_KEY=your_api_key
```

#### 模型路由

`getModel()` 按三级优先级解析模型 id：

1. 命中已注册的前缀，使用该自定义提供商
2. 配置了 `AI_BASE_URL`，以 OpenAI 兼容协议直连该端点
3. 兜底走 AI Gateway

不配置 `AI_BASE_URL` 时所有模型走 AI Gateway，一个 key 代理多家厂商，模型 id 保持 `provider/model` 形式。配置后请求改以 chat completions 协议直连该端点，此时模型 id 里的前缀只用于渲染下拉框图标，发请求前会被剥掉，`deepseek/deepseek-chat` 实际发送的是 `deepseek-chat`。

| 厂商 | `AI_BASE_URL` |
| --- | --- |
| DeepSeek | `https://api.deepseek.com/v1` |
| 阿里云通义千问（国际） | `https://dashscope-intl.aliyuncs.com/compatible-mode/v1` |
| 阿里云通义千问（国内） | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
| 智谱 GLM | `https://open.bigmodel.cn/api/paas/v4` |

> [!NOTE]
> 
> 一组 
> 
> AI_API_KEY
> 
>  + 
> 
> AI_BASE_URL
> 
>  只对应一个上游，
> 
> models
> 
>  列表请填同一厂商的模型。需要同时接入多家厂商时，改用上面的自定义提供商注册。

### 系统提示词

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

[](https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/modules/ai-chat/runtime/server/api/ai-chat.ts)

### 样式

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

## API

### `AiChat`

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

[](https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/modules/ai-chat/runtime/components/AiChat.vue)

### `AiChatFloatingInput`

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

**键盘快捷键：**

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

> [!NOTE]
> 
> 需使用 
> 
> Teleport
> 
>  和 
> 
> ClientOnly
> 
>  包裹以确保正确渲染。

[](https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/modules/ai-chat/runtime/components/AiChatFloatingInput.vue)

### `AiChatModelSelect`

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

> [!NOTE]
> 
> 该组件会自动显示 
> 
> nuxt.config.ts
> 
>  中配置的 
> 
> models
> 
>  列表，并使用 
> 
> useModels
> 
>  组合式函数管理模型状态。

[](https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/modules/ai-chat/runtime/components/AiChatModelSelect.vue)

### `AiChatPanel`

完整的 AI 聊天面板界面。

**特性：**

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

[](https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/modules/ai-chat/runtime/components/AiChatPanel.vue)

### `AiChatDisabled`

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

[](https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/modules/ai-chat/runtime/components/AiChatDisabled.vue)

## Composables

### `useAIChat()`

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

#### 返回值

**isOpen** (`Ref<boolean>`): 对话框是否打开的响应式状态。

**messages** (`Ref<UIMessage[]>`): 消息列表，包含所有历史对话记录。

**open** (`(text: string) => void`): 打开对话框并发送初始消息。初始消息，打开对话框时自动发送。

**toggleChat** (`() => void`): 切换对话框的打开/关闭状态。

### `useModels()`

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

#### 返回值

**models** (`Ref<string[]>`): 可用模型列表，从 nuxt.config.ts 的 aiChat.models 配置读取。

**model** (`Ref<string>`): 当前选中的模型 ID，会持久化到 localStorage。

**formatModelName** (`(modelId: string) => string`): 格式化模型 ID 为易读的显示名称（去除前缀和后缀）。模型 ID，格式如 anthropic/claude-sonnet-4.6。

### `useHighlighter()`

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

#### 返回值

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

> [!NOTE]
> 
> **支持的语言：** `vue`, `js`, `ts`, `css`, `html`, `json`, `yaml`, `markdown`, `bash`
> 
> **支持的主题：**
> 
> - `material-theme-palenight`（深色模式）
> - `material-theme-lighter`（浅色模式）

```ts
const highlighter = await useHighlighter()

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

### `useToolCall(state, toolName, input)`

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

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

#### 参数

**state** (`ToolState`): 工具调用状态，可判断是否已完成：'output-available' 表示已完成，其他值表示进行中。

**toolName** (`string`): 工具名称，与 MCP 工具定义中的 name 字段对应。

**input** (`Record<string, string | undefined>`): 工具调用的输入参数。

#### 返回值

**toolMessage** (`Record<string, string>`): 工具名到显示文本的映射。键为工具名，值为对应的显示文本。未匹配的工具名会回退到默认文本。

**toolIcon** (`Record<string, string>`): 工具名到图标的映射。键为工具名，值为 Iconify 图标名。未匹配的工具名会回退到 i-lucide-search。

#### 扩展自定义工具

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

```ts [composables/useToolCall.ts]
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 工具裁剪，并由同一份配置同时生成显示文本与图标：

| 工具名 | 显示文本 | 图标 |
| --- | --- | --- |
| `search-documentation` | 搜索中 / 已搜索 文档页面，可附带 `section`、`search` 条件 | `i-lucide-book-search` |
| `search-composables` | 搜索中 / 已搜索 组合函数，可附带 `search` 条件 | `i-lucide-braces` |
| `search-icons` | 搜索中 / 已搜索 图标，可附带 `query` 条件 | `i-lucide-search` |
| `list-examples` | 搜索中 / 已搜索 示例 | `i-lucide-codesandbox` |
| `get-documentation-page` | 读取中 / 已读取 `{path}` 页面 | `i-lucide-book-open` |
| `get-example` | 读取中 / 已读取 `{exampleName}` 示例 | `i-lucide-codepen` |
| `get-component` | 读取中 / 已读取 `{componentName}` 组件文档 | `i-lucide-box` |
| `get-component-metadata` | 读取中 / 已读取 `{componentName}` 组件元数据 | `i-lucide-file-code` |


## Sitemap

See the full [sitemap](https://docs.mhaibaraai.cn/sitemap.md) for all pages.