> AI coding agents: see [/llms.txt](/llms.txt) for the full documentation index. Markdown version: [/docs/manual/zh/ai/assistant.md](/docs/manual/zh/ai/assistant.md).

---
title: 助手
description: 为您的文档添加 AI 驱动的聊天功能，回答问题、引用来源并生成代码示例。
navigation:
  icon: i-lucide-sparkles
---

## 关于助手

TockDocs 助手是一个**基于文档的对话 UI**，构建于以下技术之上：

- **AI SDK** 用于对话和模型编排
- **MCP** 用于文档工具
- **FlexSearch** 用于主要全文检索
- **Fuse.js** 用于模糊回退检索

它的设计目的是从您的文档中回答问题，而不仅仅依赖通用模型记忆。

当用户提问时，助手会：

- **搜索和检索**相关内容，通过内置的 [MCP 服务器](/docs/manual/zh/ai/mcp)
- **搜索完整页面内容**，而不仅仅是标题
- **使用模糊回退检索**，当精确搜索效果不佳时
- **引用来源**，提供返回文档的链接
- **可生成代码示例**，基于检索到的文档

## 工作原理

运行时流程是工具接地的：

1. 客户端将聊天消息发送到 `/__tockdocs__/assistant`。
2. 服务器解析活动的提供商和模型。
3. 当请求来自文档页面时，TockDocs 会尽可能将请求范围限定到当前的**知识库**和**语言**。
4. 助手向模型暴露 MCP 工具。
5. `search-pages` 首先使用 FlexSearch 进行检索，必要时使用 Fuse.js 回退。
6. 模型将接地答案流式传输回 UI。

默认情况下，助手连接到您在 `/mcp` 的内置 MCP 服务器，该服务器暴露 `search-pages`、`list-pages` 和 `get-page`。

## 快速开始

### 1. 配置模型提供商

TockDocs 支持 **Vercel AI Gateway**，以及：

- OpenRouter
- DeepSeek
- Nvidia
- Hugging Face
- Groq
- GitHub Models
- Gemini
- Cloudflare Workers AI

**Vercel AI Gateway**

```bash [.env]
AI_PROVIDER=vercel
AI_MODEL=google/gemini-3-flash
# 使用 AI_GATEWAY_API_KEY 进行手动密钥设置；Vercel 保留 VERCEL_* 前缀。
AI_GATEWAY_API_KEY=your-api-key
```

**OIDC（仅限 Vercel）** — `VERCEL_OIDC_TOKEN` 自动注入。生产环境无需添加。本地开发时，在[已关联项目](https://vercel.com/docs/cli/link)上运行 `vercel env pull`。

**其他提供商示例**

```bash [.env]
AI_PROVIDER=deepseek
DEEPSEEK_API_KEY=your-api-key
DEEPSEEK_MODEL=deepseek-chat
```

如果 `AI_PROVIDER` 未设置，TockDocs 会从您的可用凭据中自动检测第一个已配置的提供商。

### 2. 运行或部署您的站点

在开发环境中，助手 UI 自动启用。

在生产环境中，当以下任一条件满足时可用：

- `NUXT_PUBLIC_ASSISTANT_ENABLED=true`，或
- 存在受支持的提供商凭据

## 使用助手

### 浮动输入框

在文档页面上，屏幕底部会出现一个浮动输入框。用户可以直接输入问题并按 Enter 获取答案。

::tip
使用键盘快捷键 :kbd{value="meta"} :kbd{value="I"} 聚焦浮动输入框。
::

### 用 AI 解释

每个文档页面在目录侧边栏中包含一个**用 AI 解释**按钮。点击它会在当前页面上下文中打开助手。

### 侧滑聊天

当对话开始时，屏幕右侧会打开一个侧滑面板，保持对话状态可见。

## UI 配置

通过 `app.config.ts` 配置助手 UI：

```ts [app/app.config.ts]
export default defineAppConfig({
  assistant: {
    floatingInput: true,
    explainWithAi: true,
    faqQuestions: [],
    shortcuts: {
      focusInput: 'meta_i',
    },
    icons: {
      trigger: 'i-lucide-sparkles',
      explain: 'i-lucide-brain',
    },
  },
})
```

### 常见问题

当聊天为空时显示建议问题。

#### 简单格式

```ts [app/app.config.ts]
export default defineAppConfig({
  assistant: {
    faqQuestions: [
      '如何安装 TockDocs？',
      '如何自定义主题？',
      '如何向页面添加组件？',
    ],
  },
})
```

#### 分类格式

```ts [app/app.config.ts]
export default defineAppConfig({
  assistant: {
    faqQuestions: [
      {
        category: '快速入门',
        items: ['如何安装 TockDocs？', '项目结构是怎样的？'],
      },
      {
        category: '自定义',
        items: ['如何更改主题颜色？', '如何添加自定义 Logo？'],
      },
    ],
  },
})
```

#### 本地化格式

```ts [app/app.config.ts]
export default defineAppConfig({
  assistant: {
    faqQuestions: {
      en: [{ category: 'Getting Started', items: ['How do I install?'] }],
      zh: [{ category: '快速入门', items: ['如何安装？'] }],
    },
  },
})
```

## 键盘快捷键

```ts [app/app.config.ts]
export default defineAppConfig({
  assistant: {
    shortcuts: {
      focusInput: 'meta_k',
    },
  },
})
```

常用示例：

- `meta_i`
- `meta_k`
- `ctrl_shift_p`

## 高级配置

在 `nuxt.config.ts` 下的 `tockdocs.assistant` 中配置高级运行时选项：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  tockdocs: {
    assistant: {
      provider: 'vercel',
      model: 'google/gemini-3-flash',
      mcpServer: '/mcp',
      apiPath: '/__tockdocs__/assistant',
    },
  },
})
```

::warning
旧版顶层 `assistant` 配置仍可读取以保持兼容，但已弃用。请优先使用 `tockdocs.assistant`。
::

### MCP 服务器选择

您可以：

- 使用 `/mcp` 的内置 MCP 服务器
- 将助手指向外部 MCP 服务器 URL

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  tockdocs: {
    assistant: {
      mcpServer: 'https://other-docs.example.com/mcp',
    },
  },
})
```

### 提供商和模型覆盖

您可以明确指定一个提供商：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  tockdocs: {
    assistant: {
      provider: 'deepseek',
    },
  },
})
```

并可选择覆盖该提供商使用的模型：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  tockdocs: {
    assistant: {
      model: 'anthropic/claude-opus-4.5',
    },
  },
})
```

## 禁用功能

### 禁用浮动输入框

```ts [app/app.config.ts]
export default defineAppConfig({
  assistant: {
    floatingInput: false,
  },
})
```

### 禁用「用 AI 解释」

```ts [app/app.config.ts]
export default defineAppConfig({
  assistant: {
    explainWithAi: false,
  },
})
```

### 完全禁用助手

当没有可用的受支持提供商凭据且 `NUXT_PUBLIC_ASSISTANT_ENABLED` 未设置为 `true` 时，助手 UI 被禁用。

```bash [.env]
NUXT_PUBLIC_ASSISTANT_ENABLED=false
```

## 编程访问

使用 `useAssistant` 组合式函数以编程方式控制助手：

```vue
<script setup>
const { isEnabled, isOpen, open, close, toggle } = useAssistant()

function askQuestion() {
  open('如何配置主题？', true)
}
</script>

<template>
  <UButton v-if="isEnabled" @click="askQuestion">
    询问主题相关
  </UButton>
</template>
```

### 组合式函数 API

| 属性                             | 类型                   | 描述 |
| -------------------------------- | ---------------------- | ---- |
| `isEnabled`                      | `ComputedRef<boolean>` | 助手 UI 在当前运行时是否启用 |
| `isOpen`                         | `Ref<boolean>`         | 侧滑面板是否打开 |
| `open(message?, clearPrevious?)` | `Function`             | 打开助手，可附带消息 |
| `close()`                        | `Function`             | 关闭助手侧滑面板 |
| `toggle()`                       | `Function`             | 切换助手开/关 |
| `clearMessages()`                | `Function`             | 清除对话历史 |