@huyooo/ai-chat-frontend-vue

AI Chat 前端组件库 - Vue 版本。

📖 深入了解：查看 技术架构文档 了解流式渲染、Content Parts 架构、自定义 UI 注入等核心原理。

安装

npm install @huyooo/ai-chat-frontend-vue

快速开始

<template>
  <ChatPanel :adapter="adapter" />
</template>

<script setup>
import { ChatPanel } from '@huyooo/ai-chat-frontend-vue'
import '@huyooo/ai-chat-frontend-vue/style.css'
import { createElectronAdapter } from '@huyooo/ai-chat-bridge-electron/renderer'

const adapter = createElectronAdapter()
</script>

组件

ChatPanel

主聊天面板组件。

<ChatPanel
  :adapter="adapter"
  :working-dir="'/path/to/dir'"
  :default-model="'anthropic/claude-opus-4.5'"
  :default-mode="'agent'"
  :models="modelList"
  :hide-header="false"
  :welcome-config="welcomeConfig"
  @close="handleClose"
/>

Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | adapter | ChatAdapter | 必填 | 通信适配器 | | workingDir | string | - | 工作目录 | | defaultModel | string | 'anthropic/claude-opus-4.5' | 默认模型 | | defaultMode | ChatMode | 'agent' | 默认模式 | | models | ModelOption[] | [] | 可用模型列表 | | hideHeader | boolean | false | 是否隐藏标题栏 | | welcomeConfig | Partial<WelcomeConfig> | - | 欢迎页配置 | | stepsExpandedType | 'open' \| 'close' \| 'auto' | 'auto' | 执行步骤展开模式 | | toolRenderers | Record<string, Component> | {} | 自定义工具结果渲染器 | | blockRenderers | Record<string, Component> | {} | 自定义内容块渲染器 | | autoRunConfig | AutoRunConfig | - | 自动运行配置 | | onClose | () => void | - | 关闭回调 | | onToolComplete | (event: ToolCompleteEvent) => void | - | 工具执行完成回调 |

stepsExpandedType 说明

控制工具执行步骤的默认展开/折叠行为：

| 值 | 说明 | |---|------| | 'open' | 始终展开所有步骤 | | 'close' | 始终折叠所有步骤 | | 'auto' | 正在执行的步骤展开，执行完毕自动折叠 |

autoRunConfig 说明

自动运行配置用于控制 Agent 的工具执行行为：

interface AutoRunConfig {
  mode?: 'run-everything' | 'manual';  // 自动运行模式
}

配置项说明：

• mode: 自动运行模式
  • 'run-everything': 运行所有内容（自动执行）
  • 'manual': 手动批准模式（每次执行前询问）

使用示例：

<template>
  <ChatPanel
    :adapter="adapter"
    :working-dir="workingDir"
    :auto-run-config="{
      mode: 'run-everything',
    }"
  />
</template>

WelcomeMessage

欢迎页组件，支持自定义配置。

<WelcomeMessage :config="welcomeConfig" @quick-action="handleQuickAction" />

欢迎页配置

可以通过 welcomeConfig 自定义欢迎页的标题、功能列表和快捷任务。

import type { WelcomeConfig } from '@huyooo/ai-chat-frontend-vue'

const welcomeConfig: Partial<WelcomeConfig> = {
  // 标题区域
  title: '文件助手',
  subtitle: '智能文件管理 · 代码分析',
  icon: 'lucide:folder',
  
  // 功能列表
  features: [
    { name: '执行命令', icon: 'lucide:terminal' },
    { name: '文件分析', icon: 'lucide:file-search' },
    { name: '代码生成', icon: 'lucide:code' },
  ],
  
  // 快捷任务
  tasks: [
    {
      name: '列出文件',
      desc: '查看目录内容',
      prompt: '列出当前目录的文件',
      icon: 'lucide:list',
    },
    {
      name: '代码分析',
      desc: '分析代码结构',
      prompt: '分析这个项目的代码结构',
      icon: 'lucide:code',
    },
  ],
}

配置接口

interface WelcomeConfig {
  /** 标题 */
  title: string
  /** 副标题 */
  subtitle: string
  /** 图标 (Iconify 格式) */
  icon: string
  /** 功能列表 */
  features: WelcomeFeature[]
  /** 快捷任务 */
  tasks: WelcomeTask[]
}

interface WelcomeFeature {
  name: string
  icon: string
}

interface WelcomeTask {
  name: string
  desc: string
  prompt: string
  icon: string
}

默认配置

如果不传 welcomeConfig，将使用内置的默认配置。也可以只覆盖部分字段：

// 只修改标题，其他使用默认
const welcomeConfig = {
  title: '我的 AI 助手',
  subtitle: '智能对话工具',
}

可以导入默认配置作为基础：

import { defaultWelcomeConfig } from '@huyooo/ai-chat-frontend-vue'

const welcomeConfig = {
  ...defaultWelcomeConfig,
  title: '自定义标题',
}

自定义工具结果渲染器

可以为特定工具注入自定义渲染组件，替代默认的 JSON 显示：

<template>
  <ChatPanel
    :adapter="adapter"
    :tool-renderers="toolRenderers"
  />
</template>

<script setup lang="ts">
import { markRaw, type Component } from 'vue'
import { ChatPanel } from '@huyooo/ai-chat-frontend-vue'
import CustomWeatherCard from './components/CustomWeatherCard.vue'

// 工具名称 -> 渲染组件映射
const toolRenderers: Record<string, Component> = {
  get_weather: markRaw(CustomWeatherCard),
  // search_web: markRaw(CustomSearchResults),
}
</script>

创建自定义渲染组件

<!-- CustomWeatherCard.vue -->
<template>
  <div class="weather-card">
    <div class="city">{{ weather.city }}</div>
    <div class="temp">{{ weather.temperature }}°C</div>
    <div class="condition">{{ weather.condition }}</div>
    <div class="details">
      <span>湿度 {{ weather.humidity }}%</span>
      <span>{{ weather.wind }}</span>
    </div>
  </div>
</template>

<script setup lang="ts">
import { computed } from 'vue'
import type { ToolRendererProps, WeatherData } from '@huyooo/ai-chat-shared'

const props = defineProps<ToolRendererProps>()

const weather = computed<WeatherData>(() => {
  if (typeof props.toolResult === 'object' && props.toolResult !== null) {
    return props.toolResult as WeatherData
  }
  return { city: '未知', temperature: 0, condition: '未知' }
})
</script>

ToolRendererProps 接口

interface ToolRendererProps {
  toolName: string      // 工具名称
  toolArgs: object      // 工具调用参数
  toolResult: unknown   // 工具返回结果
  status: 'running' | 'done' | 'error'  // 执行状态
}

内置数据类型

// 天气数据
interface WeatherData {
  city: string
  temperature: number
  condition: string
  humidity?: number
  wind?: string
}

// 搜索结果
interface SearchResultItem {
  title: string
  url: string
  snippet: string
}

自定义内容块渲染器

可以为特定内容类型注入自定义渲染组件：

<template>
  <ChatPanel
    :adapter="adapter"
    :block-renderers="blockRenderers"
  />
</template>

<script setup lang="ts">
import { markRaw, type Component } from 'vue'
import CustomMathBlock from './components/CustomMathBlock.vue'

const blockRenderers: Record<string, Component> = {
  math: markRaw(CustomMathBlock),
}
</script>

useChat

Composable 函数，用于自定义 UI。

import { useChat } from '@huyooo/ai-chat-frontend-vue'

const {
  messages,
  isLoading,
  sendMessage,
  regenerateMessage,
  abort,
  clearHistory,
} = useChat({ adapter })

导出

// 主组件
export { ChatPanel, WelcomeMessage, ChatInput, ChatHeader, MessageBubble }

// 内容渲染组件
export { ContentRenderer, TextBlock, CodeBlock }

// 工具结果渲染组件
export { ToolResultRenderer, DefaultToolResult, WeatherCard, SearchResults }

// Composable
export { useChat }

// 类型 (来自 @huyooo/ai-chat-shared)
export type {
  WelcomeConfig,
  WelcomeFeature,
  WelcomeTask,
  ToolRendererProps,
  WeatherData,
  SearchResultItem,
  ContentBlock,
  TextBlock,
  CodeBlock
}

// 工具函数 (来自 @huyooo/ai-chat-shared)
export { parseContent, highlightCode, getLanguageDisplayName }

// 默认配置
export { defaultWelcomeConfig }

License

MIT