langgraph-vue3-chatbot

一个面向 Vue 3 的 AI 聊天组件库，基于 @langchain/langgraph-sdk 实现与 LangGraph 后端的流式通信。

当前提供两个核心组件：

• AskAiBot：悬浮按钮 + 展开聊天窗，适合挂在页面右下角快速唤起
• ChatBot：可直接嵌入页面的聊天面板，适合详情页、工作台、后台系统等场景

组件内部已集成：流式消息渲染、工具调用展示、附件能力、建议问题、模型选择、浅色/深色主题切换等常见 AI 聊天能力。

预览

特性

• 开箱即用的 Vue 3 AI 聊天组件
• 基于 LangGraph 的流式消息通信
• 同时支持嵌入式面板和悬浮聊天窗
• 内置工具调用展示
• 支持附件上传入口插槽
• 支持建议问题、空状态、自定义消息内容插槽
• 自动引入组件样式，接入成本低
• 使用 TypeScript 编写，提供类型声明

安装

宿主项目需自行提供 vue，其余运行时依赖会随 langgraph-vue3-chatbot 自动安装，无需额外手动安装 markstream-vue、mermaid、shiki 等依赖。

pnpm add langgraph-vue3-chatbot

快速开始

1. 准备 LangGraph 服务

组件默认通过以下参数连接 LangGraph 后端：

• apiUrl：LangGraph 服务地址
• apiKey：LangGraph 服务访问凭证（可选）
• assistantId：目标 assistant 标识

本地开发时，常见配置类似：

VITE_LANGGRAPH_API_URL=http://localhost:2024
VITE_LANGGRAPH_ASSISTANT_ID=demo-assistant
VITE_LANGGRAPH_ASSISTANT_NAME=AI 助手

2. 使用 AskAiBot

适合在现有页面中增加一个可随时唤起的 AI 助手入口。

<script setup lang="ts">
import { AskAiBot } from 'langgraph-vue3-chatbot'
</script>

<template>
  <AskAiBot
    assistant-id="research"
    assistant-name="AI 助手"
    api-url="http://localhost:2024"
    theme="light"
    :width="400"
    height="calc(100vh - 120px)"
    :allow-model-switch="false"
  />
</template>

3. 使用 ChatBot

适合直接嵌入业务页面，作为主要聊天区域。

<script setup lang="ts">
import { ChatBot } from 'langgraph-vue3-chatbot'
</script>

<template>
  <div style="height: 600px;">
    <ChatBot
      assistant-id="research"
      assistant-name="AI 助手"
      api-url="http://localhost:2024"
      theme="dark"
      :show-header-actions="false"
      :allow-model-switch="false"
    />
  </div>
</template>

推荐接入方式

如果你希望接入方式更贴近本仓库 demo，可以结合环境变量来传入配置：

<script setup lang="ts">
import { AskAiBot, ChatBot, type AiBotTheme } from 'langgraph-vue3-chatbot'

const apiUrl = import.meta.env.VITE_LANGGRAPH_API_URL || 'http://localhost:2024'
const assistantId = import.meta.env.VITE_LANGGRAPH_ASSISTANT_ID || 'demo-assistant'
const assistantName = import.meta.env.VITE_LANGGRAPH_ASSISTANT_NAME || 'AI 助手'
const chatbotTheme: AiBotTheme = 'light'
const askAiBotTheme: AiBotTheme = 'dark'

const suggestions = [
  '这个 demo 怎么接入真实服务？',
  'ChatBot 和 AskAiBot 分别适合什么场景？',
]
</script>

<template>
  <ChatBot
    :api-url="apiUrl"
    :assistant-id="assistantId"
    :assistant-name="assistantName"
    :theme="chatbotTheme"
  />

  <AskAiBot
    :api-url="apiUrl"
    :assistant-id="assistantId"
    :assistant-name="assistantName"
    :suggestions="suggestions"
    :theme="askAiBotTheme"
  />
</template>

Props

AskAiBot

| Prop | 用途 | 默认值 | | --- | --- | --- | | assistantId | 指定 LangGraph 侧的 assistant 标识 | 'research' | | assistantName | 设置组件头部展示的助手名称 | 'Chat' | | defaultExpanded | 控制悬浮聊天窗首次渲染时是否默认展开 | false | | systemPrompt | 设置发送给模型的系统提示词 | '用中文回答' | | threadId | 指定已有会话线程 id；不传时由组件内部创建线程。传固定值时可复用历史，并在刷新后自动尝试加入该线程最近的活跃对话流 | undefined | | userId | 标识当前用户，用于请求上下文区分 | 'user001' | | suggestions | 配置输入区上方的建议问题列表 | [] | | apiUrl | 指定 LangGraph 服务地址 | 'http://localhost:2024' | | apiKey | 指定 LangGraph 服务访问凭证 | undefined | | theme | 设置组件主题，可选 light / dark | 'light' | | width | 设置悬浮聊天窗打开后的宽度，支持 number 或 CSS 尺寸字符串 | 400 | | height | 设置悬浮聊天窗打开后的高度，支持 number 或 CSS 尺寸字符串 | 'calc(100vh - 90px)' | | allowModelSwitch | 控制是否显示输入区右下角的模型选择器 | true |

ChatBot

| Prop | 用途 | 默认值 | | --- | --- | --- | | assistantId | 指定 LangGraph 侧的 assistant 标识 | 'research' | | assistantName | 设置聊天面板头部展示的助手名称 | 'Chat' | | systemPrompt | 设置发送给模型的系统提示词 | '你是一个有用的助手，帮用户解决各种问题。' | | threadId | 指定已有会话线程 id；不传时由组件内部创建线程。传固定值时可复用历史，并在刷新后自动尝试加入该线程最近的活跃对话流 | undefined | | userId | 标识当前用户，用于请求上下文区分 | 'user001' | | showHeaderActions | 控制是否显示聊天面板头部右侧操作按钮，例如关闭、最大化等 | true | | suggestions | 配置输入区上方的建议问题列表 | [] | | apiUrl | 指定 LangGraph 服务地址 | 'http://localhost:2024' | | apiKey | 指定 LangGraph 服务访问凭证 | undefined | | theme | 设置组件主题，可选 light / dark | 'light' | | allowModelSwitch | 控制是否显示输入区右下角的模型选择器 | true |

组件实例 API

ChatBot 和 AskAiBot 都支持通过 ref 调用少量公开实例方法。

公共能力：

• setTextInput(text: string)：设置输入框文本
• addAttachments(attachments: PromptInputAttachment[])：添加附件，支持 file、data + mediaType、file_url 三种模式
• sendMessage()：触发现有发送流程

其中：

• ChatBot 会直接调用内部输入区现有逻辑
• AskAiBot 在折叠状态下调用 sendMessage() 时，会先自动展开再发送

AskAiBot 额外支持：

• open()：打开悬浮聊天窗
• close()：关闭悬浮聊天窗；如果当前处于最大化状态，会一并退出最大化

ChatBot 示例

PromptInputAttachment 推荐按以下三种模式传入：

1. 本地文件

{ type: 'file' | 'image', file: File, filename?: string, mediaType?: string }

• file：浏览器原生 File 对象
• filename / mediaType：可选覆盖默认文件名和 MIME 类型

2. 内联内容

{ type: 'file' | 'image', filename: string, mediaType: string, data: string }

• data：纯 base64 内容
• data 不要带 data:image/png;base64, 这类前缀
• mediaType：文件 MIME 类型，例如 image/png、application/pdf

3. 远程地址

{ type: 'file_url', url: string, filename?: string, mediaType?: string }

• url：远程文件地址
• filename / mediaType：可选补充展示信息

<script setup lang="ts">
import { ref } from 'vue'
import { ChatBot, type AiBotPublicApi, type PromptInputAttachment } from 'langgraph-vue3-chatbot'

const chatBotRef = ref<AiBotPublicApi | null>(null)

function askWithAttachment() {
  chatBotRef.value?.setTextInput('请帮我分析这些附件')

  const attachments: PromptInputAttachment[] = [
    {
      type: 'file_url',
      url: 'https://example.com/report.pdf',
      filename: 'report.pdf',
      mediaType: 'application/pdf'
    },
    {
      type: 'image',
      filename: 'architecture.png',
      mediaType: 'image/png',
      data: 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVQIHWP4////fwAJ+wP9KobjigAAAABJRU5ErkJggg=='
    }
  ]

  chatBotRef.value?.addAttachments(attachments)
  chatBotRef.value?.sendMessage()
}
</script>

<template>
  <button @click="askWithAttachment">
    发送预设问题
  </button>

  <div style="height: 600px; margin-top: 12px;">
    <ChatBot
      ref="chatBotRef"
      assistant-id="research"
      assistant-name="AI 助手"
      api-url="http://localhost:2024"
    />
  </div>
</template>

AskAiBot 示例

<script setup lang="ts">
import { ref } from 'vue'
import { AskAiBot, type AskAiBotPublicApi } from 'langgraph-vue3-chatbot'

const askAiBotRef = ref<AskAiBotPublicApi | null>(null)

function openBot() {
  askAiBotRef.value?.open()
}

function closeBot() {
  askAiBotRef.value?.close()
}

function quickAsk() {
  askAiBotRef.value?.setTextInput('帮我总结今天的待办')
  askAiBotRef.value?.sendMessage()
}
</script>

<template>
  <div style="display: flex; gap: 8px;">
    <button @click="openBot">
      打开助手
    </button>
    <button @click="closeBot">
      关闭助手
    </button>
    <button @click="quickAsk">
      唤起并发送
    </button>
  </div>

  <AskAiBot
    ref="askAiBotRef"
    assistant-id="research"
    assistant-name="AI 助手"
    api-url="http://localhost:2024"
  />
</template>

Slots

AskAiBot

| Slot | 用途 | Slot Props | | --- | --- | --- | | empty | 自定义空状态内容 | { sendMessage } | | custom | 自定义 custom 消息渲染 | { customContent, threadId } | | attachment-trigger | 自定义附件触发器 | { addAttachments } |

ChatBot

| Slot | 用途 | Slot Props | | --- | --- | --- | | empty | 自定义空状态内容 | { sendMessage } | | custom | 自定义 custom 消息渲染 | { customContent, threadId } | | attachment-trigger | 自定义附件触发器 | { addAttachments } |

样式说明

• 组件通过主入口导出
• 主入口会自动带出组件样式
• 使用时无需额外单独引入样式文件
• 当前内置两套主题：light（浅色，默认）与 dark（深色）
• AskAiBot 的 theme 会同时作用于外层悬浮按钮、内部 ChatBot 与 portal 浮层
• 内部 markdown 渲染基于 markstream-vue，代码高亮会随主题自动切换：
  • light -> vitesse-light
  • dark -> vitesse-dark

使用建议

• 页面内主聊天区域优先使用 ChatBot
• 作为全局 AI 助手入口优先使用 AskAiBot
• 如果你已经有 thread id，可通过 threadId 复用已有会话
• 当传入固定 threadId 时，组件会先恢复线程历史；如果该线程存在 pending / running 的最近 run，会在页面刷新后自动重新加入流式对话
• 当前续流是基于线程最近活跃 run 的恢复，不是严格的事件级断点续传；极短时间窗口里的部分中间 chunk 仍可能丢失
• 续流阶段会临时隐藏 custom 消息，等流结束后自动恢复显示，避免旧的自定义事件插在正在打字的 AI 消息中间
• 如果需要区分用户上下文，可传入 userId

如需了解续流实现细节、边界和维护注意事项，可参考 docs/stream-resume.md。

本地开发

pnpm install
pnpm dev

构建生产版本：

pnpm build

预览构建结果：

pnpm preview

相关链接

• npm: https://www.npmjs.com/package/langgraph-vue3-chatbot
• Repository: https://github.com/izerui/langgraph-vue3-chatbot

License

MIT