@bztribe/agent-ui

@bztribe/agent-ui

general-agent（嵌入宿主进程的 Agent 能力栈）官方 Vue3 + TypeScript 前端组件库：供任意宿主工程快速集成 Agent 对话能力（可选接入；也可基于 REST/SSE/WebSocket 自定义开发）。

宿主把能力栈的 Handler() 挂到自己的 http.Server 上（或按 demo 形态做 Facade 代理）， 组件库的 baseUrl 即指向该宿主地址。

能力

类型与后端对齐：internal/common/response（统一响应/分页）与 service.AgentEvent（think / tool_call / tool_result / text / done / error）。

安装

npm install @bztribe/agent-ui
# peer dependency: vue ^3.4

身份透传

本工程不做鉴权，安全边界由宿主（网关/登录态）承担。组件库不内置任何凭证， 需要携带租户/身份时经 headers 透传（能力栈侧透传即信任，用于数据归属、隔离、成本核算）：

new AgentClient({ headers: { 'X-Tenant-Id': 'demo-tenant' } })

快速开始

1. 直接使用聊天组件

<script setup lang="ts">
import { AgentClient, AgentChat } from '@bztribe/agent-ui'
import '@bztribe/agent-ui/styles.css'

const client = new AgentClient({
  baseUrl: 'https://host.example.com', // 宿主对外地址；默认同源，可省略
})
</script>

<template>
  <AgentChat :client="client" :agent-id="42" style="height: 560px" />
</template>

2. 用组合式函数自定义 UI

<script setup lang="ts">
import { AgentClient, useAgentChat } from '@bztribe/agent-ui'

const client = new AgentClient()
// 外部注入业务上下文：静态值或动态 provider（每次发送时解析，仅本次请求生效）
const chat = useAgentChat(client, 42, {
  context: () => `当前页面：${route.name}；用户：${store.userName}`,
})

// 指定会话/模型续聊
chat.send('帮我查一下订单', { session_id: 1001, model: 'qwen2.5:14b' })
</script>

<template>
  <div v-for="(m, i) in chat.messages.value" :key="i">
    <b>{{ m.role }}:</b> {{ m.content }}<span v-if="m.streaming">▊</span>
  </div>
  <button @click="chat.busy.value ? chat.stop() : chat.reset()">停止 / 清空</button>
</template>

<AgentChat> 同样支持 context prop（静态/动态 provider）；WebSocket 通道 agentWS.send(query, sessionId?, context?) 按次注入。服务端把 context 拼接到 system prompt 前部（标注为"宿主注入的背景信息"），不落库、不进版本快照。

3. 只要底层 API / SSE

import { AgentClient, streamAgent } from '@bztribe/agent-ui'

const client = new AgentClient()
const result = await client.executeAgent(42, { query: '总结这个告警' })

const abort = streamAgent(42, { query: '总结这个告警' }, {
  baseUrl: client.baseUrl,
  onEvent(ev) {
    // ev.type: think | tool_call | tool_result | text | done | error
    console.log(ev.type, ev.data)
  },
  onError: console.error,
})
// abort() 可中断流

4. WebSocket 双向通道（同一连接多轮执行）

import { agentWS } from '@bztribe/agent-ui'

const ws = agentWS(42, {
  onEvent(ev) { console.log(ev.type, ev.data) }, // 事件结构与 SSE 对齐
  onClose() { /* 服务端断开 */ },
})
ws.send('查一下订单 A1001') // 第一轮
ws.send('再查 A1002')       // 同一连接多轮复用；ping 保活自动进行
ws.close()                   // 主动断开

本地开发

cd web
npm install
npm run typecheck   # vue-tsc 类型检查
npm run build       # 产出 dist/（esm + umd + d.ts + styles）
npm run playground  # 启动组件试验场 http://localhost:5174（全部组件一次看全）

Playground（组件试验场）

playground/ 页面可视化展示全部组件（AgentChat / SessionList / ApprovalCard / RagDocs / TraceView / CostBoard / WorkflowPanel），顶部可实时调 BaseURL / AgentID / 主题（light|dark）/ 语言（zh|en），供宿主选型评估。独立于 lib 构建（npm run build 只打包 src/index.ts）。

发布到 npm（维护者）

包名为 scoped 包（@bztribe/agent-ui），必须带 --access public，否则默认发布为私有：

cd web
npm login                      # 需为 npm 上 bztribe scope（org）的成员
npm run build
npm pack --dry-run             # 核对产物仅含 dist/
npm publish --access public    # 版本号须与仓库统一 tag vX.Y.Z 一致（见根 CHANGELOG.md）

发版顺序：改版本号 → npm run build → commit → 打统一 tag vX.Y.Z（与 CHANGELOG 对齐）→ npm publish --access public。