@netstar/ai-chat

Vue 3 AI 对话面板组件 — 可复用的智能对话 UI 组件，支持多 Agent 切换、工具调用可视化、人工审批流程。

安装

npm install @netstar/ai-chat
# peer dependencies
npm install vue ant-design-vue ant-design-x-vue @ant-design/icons-vue

快速开始

<template>
  <ChatPanel
    :agents="agents"
    :roles="roles"
    v-model="inputText"
    v-model:agent-key="currentAgent"
    @submit="handleSubmit"
    @cancel="handleCancel"
    @reset="handleReset"
  />
</template>

<script setup lang="ts">
  import { ChatPanel, type AgentOption } from '@netstar/ai-chat';
  import '@netstar/ai-chat/style.css';

  const agents: AgentOption[] = [
    {
      key: 'assistant',
      label: '通用助手',
      agent: myAgentInstance,
    },
  ];

  const roles = {
    user: { placement: 'end' },
    ai: { placement: 'start' },
  };
</script>

核心概念

AgentRuntime 接口

ChatPanel 通过 AgentRuntime 接口与具体 AI 后端解耦。任何实现了该接口的对象均可作为 Agent 传入：

import type { AgentRuntime } from '@netstar/ai-chat';

class MyAgent implements AgentRuntime {
  async ask(query: string) {
    /* SSE 流式请求 */
  }
  stop() {
    /* 中止请求 */
  }
  reset() {
    /* 清空历史 */
  }
  on(event, handler) {
    /* 注册事件 */
  }
  off(event, handler) {
    /* 移除事件 */
  }
  // ...
}

工具调用可视化

当 Agent 在流式响应中触发工具调用时，ChatPanel 会自动渲染 ToolCallNode 组件展示工具的执行状态。可通过 toolRenderers 自定义特定工具的渲染组件。

人工审批 (Human-in-the-Loop)

实现了 ExtendedAgentRuntime 的 Agent 支持中断/审批流程：

• 工具调用需要审批时，ChatPanel 自动显示审批 UI
• 支持批准、拒绝、修改后批准三种决策

Props

| 属性 | 类型 | 默认值 | 说明 | | ---------------------- | ---------------------------- | ------------ | ------------------------- | | title | string | '对话助手' | 面板标题 | | agents | AgentOption[] | 必填 | Agent 列表 | | agentKey | string | — | 当前 Agent (v-model) | | modelValue | string | — | 输入框内容 (v-model) | | roles | Record<string, any> | 必填 | BubbleList 角色配置 | | sessionKey | string | — | 会话 key，变化时重置 | | initialMessages | ChatMessage[] | [] | 初始历史消息 | | defaultToolRenderers | ToolRendererMap | — | 全局工具渲染映射 | | customHtmlTags | string[] | — | Markdown 自定义 HTML 标签 | | customComponents | MarkdownCustomComponentMap | — | Markdown 自定义组件 |

导出

• ChatPanel — 主对话面板组件
• AgentPicker — Agent 选择器组件
• ToolCallNode — 工具调用节点组件
• StreamMarkdown — 流式 Markdown 渲染组件
• 类型 — 完整的 TypeScript 类型定义

License

MIT