@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"
  />
</template>

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

  const agent = new Langchain_py_AIMessage_V3({
    endpoint: 'http://localhost:8000/langgraph/stream',
    historyEndpoint: 'http://localhost:8000/history',
  });

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

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

核心概念

AgentRuntime 接口

ChatPanel 通过 AgentRuntime 接口与 AI 后端解耦，支持多种后端实现：

| 实现 | 说明 | |---|---| | Langchain_py_AIMessage_V3 | 推荐 — LangGraph Python V3 SSE 流式接口，支持思考过程、子智能体 | | Langchain_py_AIMessage | LangGraph Python V1/V2 SSE 流式接口 | | AI_SDK_AIMessage | Vercel AI SDK 前端 Agent | | AI_SDK_Save_AIMessage | Vercel AI SDK + 服务端历史持久化 | | Dify_SDK_AIMessage | Dify 平台 API |

消息渲染（V3 blocks）

V3 Agent 通过 MessageBlock[] 描述消息的完整生命周期，ChatPanel 自动按阶段渲染：

💡 思考：需要调用子智能体计算...
     ┌─ general-purpose ─ 子代理 ──┐
     │ 💡 思考：解析表达式...         │
     │ ┌─ calculator ──────────────┐│
     │ │ input: 10+10  output: 20  ││
     │ └───────────────────────────┘│
     │ 结果为 20                      │
     └───────────────────────────────┘
     子智能体返回结果 20
10 + 10 = **20**

• ReasoningBlock — 思考/推理内容，折叠在思考容器内
• TextBlock — 回复文本
• ToolCallBlock — 工具调用节点，渲染为 ToolCallNode
• subAgentBlocks — 子智能体的完整消息流，渲染为 SubAgentNode

工具调用可视化

通过 toolRenderers 为特定工具名提供自定义渲染组件，未匹配的工具回退到 ToolCallNode。

子智能体

当 V3 Agent 调用 task 工具时，ChatPanel 渲染 SubAgentNode 组件展示子智能体的完整推理过程，包括其思考内容、工具调用和输出。

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

实现了 ExtendedAgentRuntime 的 Agent 支持中断/审批流程，支持批准、拒绝、修改后批准三种决策。

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 — 主对话面板
• AgentChat — 多 Agent 对话容器
• AgentPicker — Agent 选择器
• ToolCallNode — 工具调用时间线节点
• SubAgentNode — 子智能体渲染节点
• StreamMarkdown — 流式 Markdown 渲染
• ThinkNode — 思考内容渲染节点
• WriteTodosTopPanel — 待办面板
• SaveModuleDocsRenderer — 文档保存渲染器

Agent 运行时

• Langchain_py_AIMessage_V3 — LangGraph V3 SSE（推荐）
• Langchain_py_AIMessage — LangGraph V1/V2 SSE
• AI_SDK_AIMessage — Vercel AI SDK
• AI_SDK_Save_AIMessage — Vercel AI SDK + 历史持久化
• Dify_SDK_AIMessage — Dify 平台

工具函数

• convertHistoryRecord / convertConversationDetail — 历史记录转换
• extractTextContent / parseOpenAIAssistantToolCalls — 消息解析

类型

所有类型通过 @netstar/ai-chat 统一导出，包括 ChatMessage、MessageBlock、AgentRuntime、ExtendedAgentRuntime、ToolCallEvent、ToolTimelineItem 等。

License

MIT