Assistant

为文档添加 AI 聊天能力，用于回答问题、引用来源并生成代码示例。

关于 Assistant

Assistant 通过自然语言查询回答与文档相关的问题。它直接嵌入到你的文档站点中，让用户可以更快找到答案并顺利使用你的产品。

当用户提问时，Assistant 会：

使用 MCP server搜索并检索文档中的相关内容。
通过可导航链接引用来源，将用户直接带到被引用页面。
生成可复制的代码示例，帮助用户根据文档实现解决方案。

工作原理

Assistant 使用多 agent 架构：

Main Agent - 接收用户问题，并决定何时搜索文档
Search Agent - 使用 MCP server 工具查找相关内容
Response Generation - 将信息综合成有帮助、对话式的回答

默认情况下，Assistant 会连接到文档内置的 /mcp MCP server，无需额外配置即可访问所有页面。你也可以按需连接外部 MCP server。

快速开始

1. 安装依赖

npm install ai @ai-sdk/vue @ai-sdk/gateway @ai-sdk/mcp @comark/nuxt

pnpm add ai @ai-sdk/vue @ai-sdk/gateway @ai-sdk/mcp @comark/nuxt

yarn add ai @ai-sdk/vue @ai-sdk/gateway @ai-sdk/mcp @comark/nuxt

2. 设置 AI Gateway 认证

从以下方式中选择一种：

API key — 在 Vercel AI Gateway 创建 key，并添加到环境变量：

.env

AI_GATEWAY_API_KEY=your-api-key

OIDC（仅限 Vercel） — VERCEL_OIDC_TOKEN 会自动注入。生产环境无需额外添加。本地开发时，请在已关联项目上运行 vercel env pull。

3. 部署

部署你的站点。认证配置完成后，Assistant 即可使用。

使用 Assistant

用户可以通过多种方式与 Assistant 交互：

浮动输入框

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

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

Explain with AI

每个文档页面的目录侧边栏都包含 Explain with AI 按钮。点击后会打开 Assistant，并以当前页面作为上下文，请它解释内容。

Slideover 聊天

对话开始后，屏幕右侧会打开一个 slideover 面板。该面板显示对话历史，并允许用户继续提问。

配置

通过 app.config.ts 配置 Assistant：

app.config.ts

export default defineAppConfig({
  assistant: {
    // Show the floating input on documentation pages
    floatingInput: true,

    // Show the "Explain with AI" button in the sidebar
    explainWithAi: true,

    // FAQ questions to display when chat is empty
    faqQuestions: [],

    // Keyboard shortcuts
    shortcuts: {
      focusInput: 'meta_i'
    },

    // Custom icons
    icons: {
      trigger: 'i-lucide-sparkles',
      explain: 'i-lucide-brain'
    }
  }
})

FAQ 问题

当聊天为空时显示推荐问题，帮助用户了解可以询问什么。

简单格式

app.config.ts

export default defineAppConfig({
  assistant: {
    faqQuestions: [
      'How do I install Docus?',
      'How do I customize the theme?',
      'How do I add components to my pages?'
    ]
  }
})

分类格式

按分类组织问题：

app.config.ts

export default defineAppConfig({
  assistant: {
    faqQuestions: [
      {
        category: 'Getting Started',
        items: [
          'How do I install Docus?',
          'What is the project structure?'
        ]
      },
      {
        category: 'Customization',
        items: [
          'How do I change the theme colors?',
          'How do I add a custom logo?'
        ]
      }
    ]
  }
})

本地化格式

对于多语言文档，可以按 locale 提供 FAQ 问题：

app.config.ts

export default defineAppConfig({
  assistant: {
    faqQuestions: {
      en: [
        { category: 'Getting Started', items: ['How do I install?'] }
      ],
      'zh-cn': [
        { category: '快速开始', items: ['如何安装？'] }
      ]
    }
  }
})

键盘快捷键

配置聚焦浮动输入框的键盘快捷键：

app.config.ts

export default defineAppConfig({
  assistant: {
    shortcuts: {
      // Default: 'meta_i' (Cmd+I on Mac, Ctrl+I on Windows)
      focusInput: 'meta_k' // Change to Cmd/Ctrl+K
    }
  }
})

快捷键格式使用下划线分隔按键。常见示例：

meta_i - Cmd+I (Mac) / Ctrl+I (Windows)
meta_k - Cmd+K (Mac) / Ctrl+K (Windows)
ctrl_shift_p - Ctrl+Shift+P

自定义图标

自定义 Assistant 使用的图标：

app.config.ts

export default defineAppConfig({
  assistant: {
    icons: {
      // Icon for the trigger button and slideover header
      trigger: 'i-lucide-bot',

      // Icon for the "Explain with AI" button
      explain: 'i-lucide-lightbulb'
    }
  }
})

图标使用 Iconify 格式（例如 i-lucide-sparkles、i-heroicons-sparkles）。

国际化

所有 UI 文案都会根据用户的 locale 自动翻译。Docus 内置了英文和简体中文翻译。

以下文案会被翻译：

Slideover 标题和 placeholder
Tooltip 文案
按钮标签（“Clear chat”、“Close”、“Explain with AI”）
状态消息（“Thinking...”、“Chat is cleared on refresh”）

禁用功能

禁用浮动输入框

隐藏文档页面底部的浮动输入框：

app.config.ts

export default defineAppConfig({
  assistant: {
    floatingInput: false
  }
})

禁用 “Explain with AI”

隐藏文档侧边栏中的 “Explain with AI” 按钮：

app.config.ts

export default defineAppConfig({
  assistant: {
    explainWithAi: false
  }
})

完全禁用 Assistant

当没有可用认证时，Assistant 会被禁用。要显式禁用它，请从环境变量中移除 AI_GATEWAY_API_KEY：

.env

# AI_GATEWAY_API_KEY=your-api-key

在使用 OIDC 的 Vercel 项目中，请从项目设置中移除自动注入的系统环境变量。

高级配置

在 nuxt.config.ts 的 docus.assistant 下配置高级选项。

nuxt.config.ts

export default defineNuxtConfig({
  docus: {
    assistant: {
      // AI model (uses AI SDK Gateway format)
      model: 'google/gemini-3-flash',

      // MCP server (path or URL)
      mcpServer: '/mcp',

      // API endpoint path
      apiPath: '/__docus__/assistant'
    }
  }
})

MCP Server 配置

Assistant 使用 MCP server 访问你的文档。你有两个选择：

使用内置 MCP Server（默认）

默认情况下，Assistant 使用 Docus 内置的 /mcp MCP server：

nuxt.config.ts

export default defineNuxtConfig({
  docus: {
    assistant: {
      mcpServer: '/mcp'
    }
  }
})

请确保 MCP server 已在配置中启用。如果你自定义了 MCP 路径，请相应更新 mcpServer。

使用外部 MCP Server

通过提供完整 URL 连接任意外部 MCP server：

nuxt.config.ts

export default defineNuxtConfig({
  docus: {
    assistant: {
      mcpServer: 'https://other-docs.example.com/mcp'
    }
  }
})

当你希望 Assistant 根据其他文档来源回答问题，或连接到集中式知识库时，这会很有用。

自定义 AI 模型

Assistant 默认使用 google/gemini-3-flash。你可以将其改为 AI SDK Gateway 支持的任意模型：

nuxt.config.ts

export default defineNuxtConfig({
  docus: {
    assistant: {
      model: 'anthropic/claude-opus-4.5'
    }
  }
})

回答中的站点名称

Assistant 会在回答中自动使用你的站点名称。请在 nuxt.config.ts 中配置站点名称：

nuxt.config.ts

export default defineNuxtConfig({
  site: {
    name: 'My Documentation'
  }
})

这会让 Assistant 以 “the My Documentation assistant” 的身份回答，并针对你的具体产品提供更明确的说明。

编程式访问

使用 useAssistant composable 以编程方式控制 Assistant：

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

function askQuestion() {
  // Open the assistant with a pre-filled question
  open('How do I configure the theme?', true)
}
</script>

<template>
  <UButton v-if="isEnabled" @click="askQuestion">
    Ask about themes
  </UButton>
</template>

Composable API

Property	Type	Description
`isEnabled`	`ComputedRef<boolean>`	Whether the assistant is enabled (`AI_GATEWAY_API_KEY` or `VERCEL_OIDC_TOKEN` at build)
`isOpen`	`Ref<boolean>`	Whether the slideover is open
`open(message?, clearPrevious?)`	`Function`	Open the assistant, optionally with a message
`close()`	`Function`	Close the assistant slideover
`toggle()`	`Function`	Toggle the assistant open/closed
`clearMessages()`	`Function`	Clear the conversation history

图片和嵌入

添加图片、视频和其他 HTML 元素

MCP Server

通过原生 MCP server 将你的文档连接到 AI 工具。