kd-chatbot-ui-vue2
v0.1.3
Published
智能体会话 UI(Vue 2.7)。请求由宿主传入 request,组件库不写死鉴权与 baseURL。
Readme
kd-chatbot-ui-vue2
Vue 2.7 智能体会话组件库。与姊妹包 kd-chatbot-ui(Vue 3)接口契约对齐;请求鉴权由宿主传入 request,组件库不写死 token / baseURL。
本包位于 Monorepo:agent-chat-components/packages/kd-chatbot-ui-vue2。
| 模式 | 组件 | 适用场景 |
|------|------|----------|
| 适配(推荐) | AgentChatAdaptPanel | 流程与 interpret 相近:组件内调接口;路径与入参由宿主配置 |
| 受控 | AgentChatPanel | 协议完全自定义:宿主自己调接口,用 props 传入 sessions |
目录
0. 与 Vue3 版差异(必读)
| 项 | Vue3(kd-chatbot-ui) | Vue2(本包) |
|----|-------------------------|--------------|
| 包名 | kd-chatbot-ui | kd-chatbot-ui-vue2 |
| Vue | ^3.5 | ^2.7(不支持 2.6 及更早) |
| UI | Element Plus | Element UI ^2.15 |
| 状态 | Pinia ^3 | Pinia ^2.1 |
| 气泡 / 输入框 | vue-element-plus-x | 包内 ChatBubble / ChatSender |
| 历史栏双向绑定 | v-model:history-open | :history-open.sync |
| 插件安装 | app.use(plugin) | Vue.use(plugin) |
| 本地存储 key | kdChatbotUi_v3 | kdChatbotUi_vue2_v1(与 Vue3 隔离) |
接口契约相同:request / endpoints / requestParams / reloadKey / responseFields / theme / tips 等与 Vue3 版一致。
不要在同一个 Vue 应用里同时安装两套包。
1. 安装与依赖
1.1 安装
npm i kd-chatbot-ui-vue2
# 或 yarn / pnpm本地联调(指向 Monorepo 内本包):
{
"dependencies": {
"kd-chatbot-ui-vue2": "link:../agent-chat-components/packages/kd-chatbot-ui-vue2"
}
}修改源码后,在 Monorepo 根目录执行:
pnpm build:vue2宿主侧如未热更新到最新 dist,可再执行一次 pnpm install / 重启开发服务。
1.2 Peer 依赖
| 包 | 版本 |
|----|------|
| vue | ^2.7 |
| vue-template-compiler | 与 vue 同版本 |
| pinia | ^2.1(配合 Vue 2.7) |
| element-ui | ^2.15 |
| echarts | ^5.5 |
| marked | ^15 / ^16 / ^18 |
| dompurify | ^3 |
1.3 宿主入口
import Vue from "vue";
import ElementUI from "element-ui";
import "element-ui/lib/theme-chalk/index.css";
import { createPinia, PiniaVuePlugin } from "pinia";
import KdChatbotUi from "kd-chatbot-ui-vue2";
import "kd-chatbot-ui-vue2/style.css";
Vue.use(ElementUI);
Vue.use(PiniaVuePlugin);
Vue.use(KdChatbotUi); // 可选:全局注册 KdChatPanel / KdChatAdaptPanel / KdChatView
const pinia = createPinia();
new Vue({
pinia,
render: h => h(App)
}).$mount("#app");也可不 Vue.use,在页面内按需引入:
import { AgentChatAdaptPanel } from "kd-chatbot-ui-vue2";
import "kd-chatbot-ui-vue2/style.css";2. AgentChatAdaptPanel(推荐)
组件内部完成:拉会话列表、创建会话、发问、轮询进度、取消、写 store。
宿主只需传:请求函数、接口地址、传参映射、隔离维度。
2.1 最小用法
<template>
<div class="agent-chat-page">
<AgentChatAdaptPanel
:request="request"
:theme="theme"
:endpoints="endpoints"
:request-params="requestParams"
:reload-key="reloadKey"
:tips="agentTips"
:show-open-in-browser="false"
/>
</div>
</template>
<script>
import { AgentChatAdaptPanel } from "kd-chatbot-ui-vue2";
import "kd-chatbot-ui-vue2/style.css";
import request from "@/utils/request";
export default {
name: "AgentChatPage",
components: { AgentChatAdaptPanel },
data() {
return {
request,
theme: "light",
/** 快捷提示(多项):value 文案 / content 发送内容 / type 提问类型 */
agentTips: [
{
id: "default_analysis",
value: "整体分析",
content: "请对动力学计算结果进行整体分析",
type: "default_analysis"
}
],
endpoints: {
createSession: "/ds-dynamics-alg-service/interpret/sessions",
listSessions: "/ds-dynamics-alg-service/interpret/sessions",
history: "/ds-dynamics-alg-service/interpret/history/:sessionId",
ask: "/ds-dynamics-alg-service/interpret/chat/ask",
cancel: "/ds-dynamics-alg-service/interpret/chat/cancel",
progress: "/ds-dynamics-alg-service/interpret/chat/progress"
}
};
},
computed: {
wellboreId() {
return String(this.$store?.state?.well?.wellboreId || "");
},
mainId() {
return String(this.$store?.state?.well?.mainId || "");
},
tripId() {
return String(this.$store?.state?.well?.tripId || "");
},
reloadKey() {
return `${this.wellboreId}|${this.mainId}|${this.tripId}`;
},
/**
* 各接口真实传参。
* - 主应用字段:在闭包里直接取(wellboreId 等)
* - 包内字段:用参数 runtime(sessionId / taskId / content / type / since)
*/
requestParams() {
const self = this;
return {
createSession: () => ({
body: {
wellbore_id: self.wellboreId,
main_id: self.mainId,
trip_id: self.tripId
}
}),
listSessions: () => ({
query: {
wellbore_id: self.wellboreId,
main_id: self.mainId,
trip_id: self.tripId
}
}),
history: runtime => ({
path: { sessionId: runtime.sessionId }
}),
ask: runtime => ({
body: {
wellbore_id: self.wellboreId,
main_id: self.mainId,
trip_id: self.tripId,
session_id: runtime.sessionId,
type: runtime.type,
content: runtime.content
}
}),
cancel: runtime => ({
body: { task_id: runtime.taskId }
}),
progress: runtime => ({
query: {
task_id: runtime.taskId,
since: runtime.since
}
})
};
}
}
};
</script>说明:
- 不必再传
:context;主应用字段写在requestParams闭包里即可。 endpoints已是完整路径(以/开头)时,不必再传base-url。- 宿主需已安装并注册 Pinia、Element UI。
2.2 Props
| 模板属性 | 类型 | 说明 |
|----------|------|------|
| request | AgentChatRequestFn | 宿主请求函数(带 token)。不传则用 fetch(无鉴权) |
| base-url | string | 可选统一前缀。endpoints 已给完整路径时可省略。模板写 base-url(不要写成 baseURL) |
| endpoints | AgentChatEndpoints | 各接口路径。以 / 开头视为站点绝对路径,不再拼 base-url |
| request-params | AgentChatRequestParams | 各接口传参映射(主应用字段 + 包内 runtime) |
| reload-key | string \| number | 井/趟等维度变化时重拉会话。建议 `${wellboreId}|${mainId}|${tripId}` |
| response-fields | AgentChatResponseFields | 响应字段名。默认 session_id / task_id / code === "OK" |
| theme | "light" \| "dark" \| "gray" \| "white" | 面板主题;white 按 light 处理 |
| tips | AgentChatTip[] | 底部快捷提示(多项)。每项:value 文案、content 发送内容、type 提问类型。不传则用默认「整体分析」 |
| texts | AgentChatTexts | 界面文案。不传用中文默认,可只覆盖部分字段:title 智能体、history 历史会话、openInBrowser 浏览器打开、newChat 新建对话、thinking 思考中、thinkingNow 正在思考、thinkingDone 思考过程、placeholder 输入分析指令...、send 发送、stop 停止生成 |
| show-open-in-browser | boolean | 是否显示「浏览器打开」,默认 true |
| poll-interval-ms | number | 进度轮询间隔,默认 500 |
| context | AgentChatContext | 已不推荐。仅兼容旧写法;新接入请用 request-params |
| required-context | string[] | 仅在仍使用 context 时做必填校验 |
2.3 Events
| 事件 | 说明 |
|------|------|
| open-browser | 点击「浏览器打开」。发送 / 切会话 / 取消由面板内部处理;新开页由宿主自行 window.open |
2.4 tips 快捷提示
agentTips: [
{
id: "default_analysis",
value: "整体分析", // 按钮文案
content: "请对动力学计算结果进行整体分析", // 发送内容
type: "default_analysis" // ask.type
}
// 继续追加即可
]也可:
import { DEFAULT_AGENT_CHAT_TIPS } from "kd-chatbot-ui-vue2";2.5 两套字段从哪里来
| 来源 | 例子 | 怎么写进请求 |
|------|------|----------------|
| 主应用 | wellboreId、mainId、tripId | 在 requestParams 闭包里直接取 |
| 包内 runtime | sessionId、taskId、content、type、since | mapper 的参数 runtime |
runtime 由包在发请求前组装,宿主不用自己存 sessionId:
- 创建会话 / 拉列表后,包从响应读出
session_id(字段名可由response-fields改) - 写入包内 store:
sessions[].id+activeId - 用户发送时取出当前会话 id,连同
content、type放进runtime - 调用你写的 mapper,例如
session_id: runtime.sessionId
taskId 同理:来自 ask / history 响应,用于 cancel、progress。
2.6 requestParams 返回结构
type AgentChatParamMapper = (
runtime: AgentChatCallRuntime
) => {
path?: Record<string, unknown>; // 替换 URL 里的 :name / {name}
query?: Record<string, unknown>; // GET 查询参数
body?: Record<string, unknown>; // POST body
};| 接口 key | 常用写法 |
|----------|----------|
| createSession | body:主应用隔离字段 |
| listSessions | query:主应用隔离字段 |
| history | path: { sessionId: runtime.sessionId } 填 :sessionId |
| ask | body:主应用字段 + runtime.sessionId/type/content |
| cancel | body: { task_id: runtime.taskId } |
| progress | query: { task_id, since } |
只写需要改的接口;未写的接口仍走包内默认 interpret 字段。
2.7 换项目时怎么改
只换字段名:
ask: runtime => ({
body: {
wellId: this.wellId, // 你们自己的主应用字段
chatId: runtime.sessionId, // 包内 sessionId → 你们的 chatId
msg: runtime.content
}
})路径占位也不同:
// endpoints
history: "/xxx/history/:conversationId"
// requestParams
history: runtime => ({
path: { conversationId: runtime.sessionId }
})响应字段不同:
<AgentChatAdaptPanel
:response-fields="{ sessionId: 'id', taskId: 'taskId', okValue: 0 }"
...
/>包读出后仍放入 runtime.sessionId / runtime.taskId,后续映射不变。
2.8 endpoints 路径规则
http(s)://...:原样使用- 以
/开头:站点绝对路径,不拼base-url - 其它相对路径:拼在
base-url后面 history支持:sessionId或{sessionId}(或你在path里声明的其它占位名)
2.9 约定接口(未覆盖 endpoints 时)
相对 base-url:
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /sessions | 创建会话 |
| GET | /sessions | 会话列表 |
| GET | /history/:sessionId | 历史 |
| POST | /chat/ask | 提问(返回 task_id) |
| POST | /chat/cancel | 取消 |
| GET | /chat/progress | 轮询进度 |
默认成功码:code === "OK"。
3. AgentChatPanel(受控模式)
宿主自己调接口,用 props 传入展示数据;用户操作通过事件抛回宿主。
3.1 Props / Events
| Props | 说明 |
|-------|------|
| sessions | AgentSession[] |
| active-id | 当前会话 id |
| history-open | 历史侧栏;用 :history-open.sync(不要用 v-model:history-open) |
| is-replying | 是否回复中 |
| tips / theme / texts / show-open-in-browser | 同适配面板 |
| Events | 说明 |
|--------|------|
| send | (payload: { text, type?, tip? }) |
| select-session | (sessionId) |
| create-session | 新建 |
| cancel-reply | 停止生成 |
| clear-session | 清空当前会话 |
| update:historyOpen | 切换历史栏(配合 .sync) |
| open-browser | 浏览器打开 |
3.2 示例
<template>
<AgentChatPanel
:sessions="sessions"
:active-id="activeId"
:history-open.sync="historyOpen"
:is-replying="isReplying"
@send="onSend"
@select-session="onSelect"
@create-session="onCreate"
@cancel-reply="onCancel"
@clear-session="onClear"
/>
</template>
<script>
import { AgentChatPanel } from "kd-chatbot-ui-vue2";
import "kd-chatbot-ui-vue2/style.css";
export default {
components: { AgentChatPanel },
data() {
return {
sessions: [],
activeId: "",
historyOpen: false,
isReplying: false
};
},
methods: {
async onSend({ text, type }) {
this.isReplying = true;
// 调你们自己的接口,写入 sessions
this.isReplying = false;
},
onSelect(id) {
this.activeId = id;
},
onCreate() {},
onCancel() {},
onClear() {}
}
};
</script>3.3 会话消息结构
interface AgentSession {
id: string;
title: string;
content: AgentMessage[];
pinned?: boolean;
badge?: number;
updatedAt?: number;
snippet?: string;
}
interface AgentMessage {
type: "ask" | "answer";
placement: "start" | "end";
content: string;
segments?: { type: "reasoning" | "answer"; content: string }[];
}流式回复:持续更新当前会话最后一条 answer.segments,再通过 :sessions 传入即可。
4. 导出一览
import {
AgentChatAdaptPanel,
AgentChatPanel,
AgentChatView,
useAgentChat,
useAgentChatStore,
createAgentChatClient,
buildInterpretContext,
INTERPRET_POLL_INTERVAL_MS,
DEFAULT_AGENT_CHAT_TIPS
} from "kd-chatbot-ui-vue2";
import type {
AgentChatEndpoints,
AgentChatRequestParams,
AgentChatRequestFn,
AgentChatCallRuntime,
AgentChatResponseFields,
AgentChatContext,
AgentSession,
AgentMessage,
AgentChatTip,
AgentChatSendPayload,
AgentChatTheme
} from "kd-chatbot-ui-vue2";默认导出为 Vue 插件:Vue.use(KdChatbotUi)。
5. 开发与发布
本包在 Monorepo 内维护:
agent-chat-components/
packages/
kd-chatbot-ui/ # Vue3
kd-chatbot-ui-vue2/ # 本包# 在 agent-chat-components 根目录
pnpm install
pnpm build:vue2 # 只构建本包
pnpm build # Vue2 + Vue3 都构建
pnpm dev:vue2 # watch 构建构建产物:dist/kd-chatbot-ui.js、dist/kd-chatbot-ui.css、类型声明。
发布(在本包目录或按你们的发包流程):
pnpm --filter kd-chatbot-ui-vue2 publish
# prepublishOnly 会先执行 build6. 怎么选模式
- 后端仍是「会话 + ask + progress 轮询」,只是路径/字段名不同 →
AgentChatAdaptPanel+endpoints+requestParams - 协议完全不同,或宿主已有完整编排 →
AgentChatPanel,自己管接口与sessions
Vue 3 项目请用姊妹包 kd-chatbot-ui,不要混用本包。
版本
- 包名:
kd-chatbot-ui-vue2 - 版本:见本目录
package.json的version - License:MIT
