TockDocs LogoTockDocs
AI coding agents: see /llms.txt for the full documentation index. Markdown version: /docs/manual/zh/ai/assistant.md.
AI

助手

为您的文档添加 AI 驱动的聊天功能，回答问题、引用来源并生成代码示例。

关于助手

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

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

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

当用户提问时，助手会：

  • 搜索和检索相关内容，通过内置的 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

.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 自动注入。生产环境无需添加。本地开发时，在已关联项目上运行 vercel env pull。

其他提供商示例

.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 获取答案。

使用键盘快捷键 聚焦浮动输入框。

用 AI 解释

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

侧滑聊天

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

UI 配置

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

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',
    },
  },
})

常见问题

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

简单格式

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

分类格式

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

本地化格式

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

键盘快捷键

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

常用示例：

  • meta_i
  • meta_k
  • ctrl_shift_p

高级配置

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

nuxt.config.ts
export default defineNuxtConfig({
  tockdocs: {
    assistant: {
      provider: 'vercel',
      model: 'google/gemini-3-flash',
      mcpServer: '/mcp',
      apiPath: '/__tockdocs__/assistant',
    },
  },
})
旧版顶层 assistant 配置仍可读取以保持兼容，但已弃用。请优先使用 tockdocs.assistant。

MCP 服务器选择

您可以：

  • 使用 /mcp 的内置 MCP 服务器
  • 将助手指向外部 MCP 服务器 URL
nuxt.config.ts
export default defineNuxtConfig({
  tockdocs: {
    assistant: {
      mcpServer: 'https://other-docs.example.com/mcp',
    },
  },
})

提供商和模型覆盖

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

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

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

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

禁用功能

禁用浮动输入框

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

禁用「用 AI 解释」

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

完全禁用助手

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

.env
NUXT_PUBLIC_ASSISTANT_ENABLED=false

编程访问

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

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

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

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

组合式函数 API

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